A simple tutorial to get started with Openclipart API. We will walk you through
First, you need to authentificate as a user, and get your user token to connect to the API.
This is done by posting username / password to /api/v2/auth/login
, like :
curl -X POST https://openclipart.org/api/v2@beta/auth/login -d "username=clemsos&password=<REDACTED>"
You should receive a JSON with your data
{
"success": true,
"status": 200,
"data": {
"auth": true,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNsZW1zb3MiLCJwZXJtaXNsdasd5ucyI6ImFkbWluIiwiaWF0IjoxNjEzNjU3Mzc5LCJleHAiOjE2MTM3NDM3Nzl9.U55WQOtq860EAIzz0kKtlW1RgrldWVvuLKZibbFaPU0",
"user": {
"username": "clemsos",
"full_name": "Clément Renaud",
"usergroup": 1
}
}
}
Even better, you can parse the response directly using bash jq
JSON parser.
curl -s -X POST https://openclipart.org/api/v2@beta/auth/login -d "username=clemsos&password=<REDACTED>" | jq .data.token
Then, export the token in your shell
export OPENCLIPART_USER_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNsZW1zb3MiLCJwZXJtaXNzaW9hfhfI6ImFkbWluIiwiaWF0IjoxNjEzNjU0Nzc4LCJleHAiOjE2MTM3NDExNzh9.aSTNVRQGh9yu4tMt7yt8jQPaP8-dEzEqBjDpEncAU3g
To auth, you will need to add to headers Authorization: Bearer <your user token>
to your request to the server (following auth0 jwt model)
You can now create your Openclipart app via /api/v2/apps/create
and receive your app id and secret.
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENCLIPART_USER_TOKEN" \
-X POST \
-d '{ "name" : "My Test App" }' \
https://openclipart.org/api/v2@beta/apps/create
The server response:
{
"success": true,
"status": 201,
"data": {
"msg": "The app 0f125c2265c9a46ac36a1dc873972b47 has been created",
"auth": true,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiaWF0IjoxNjEyODc4MzU2LCJleHAiOjE2MTI5NjQ3NTZ9.Bnx6aJ0NPSD4Owvn8OOQbDE4P8tZ8xCQDEf5VNw0IBQ",
"app": {
"rateLimit": 20,
"id": 1,
"name": "testapp",
"appid": "0f125c2265c9a46ac36a1dc873972b47",
"secret": "0f125c2265c9a46ac36a1dc873972b47",
"updatedAt": "2021-02-09T13:45:55.863Z",
"createdAt": "2021-02-09T13:45:55.863Z"
}
}
}
WRITE THIS DOWN ! This is the first and last time you will see the app secret password.
Now you can get a token for your app to connect to the Openclipart API.
To get your token, post the appid and secret to /api/v2/apps/getToken
and get a token for your app. (NB: you can also use the one you got when creating the app at the previous step).
curl -H "Content-Type: application/json" \
-H "x-openclipart-apikey: $OPENCLIPART_USER_TOKEN" \
-X POST \
-d '{ "appid" : "37d5208674202dsdd625f5008098b731", "secret" : "fe2113f37290571ds6211d7fe298124e" }' \
https://openclipart.org/api/v2@beta/apps/getToken
Here you go
{
"success": true,
"status": 200,
"data": {
"auth": true,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjM3ZDUyMDg2NzQyMDIwZmRkNsdsdwMDgwOThiNzMxIiwicGVybWlzc2lvbnMiOiJhcHAiLCJyYXRlTGltaXQiOjUwMCwiaWF0IjoxNjEzNjU3NzI1LCJleHAiOjE2MTM3NDQxMjV9.yS7y1cGAfoqH1gWszqzYwvlV9VqWLN3nwRMnlvuP4Uw",
"app": {
"name": "My Test App",
"userid": "737514",
"appid": "37d5208674202dsdd625f5008098b731",
"rateLimit": 500,
"createdAt": "2021-02-18T14:14:30.131Z"
}
}
}
Just store the token, we will use it leater in the headers under x-openclipart-apikey
to authentificate our app.
export OPENCLIPART_API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjM3ZDUyMDg2NzQyMDIwZmRkNjI1ZjUwMDgwOThiNzMdsdiwicGVybWlzc2lvbnMiOiJhcHAiLCJyYXRlTGltaXQiOjUwMCwiaWF0IjoxNjEzNjU3NzI1LCJleHAiOjE2MTM3NDQxMjV9.yS7y1cGAfoqH1gWszqzYwvlV9VqWLN3nwRMnlvuP4Uw"
Now that you have your api token, you can start using Openclipart API !
Now let’s search using /api/v2/search/
.
curl -H "x-openclipart-apikey: $OPENCLIPART_API_TOKEN" \
?q=water https://openclipart.org/api/v2@beta/search
{
"success" : true,
"status" : 200,
"data" : {
"files" : ...,
"total_results":1961,
"files_count":25
}
}
Now head to https://openclipart.org/api-docs/ to access the complete documentation and start using it.