HOWTO Openclipart API – a tutorial

A simple tutorial to get started with Openclipart API. We will walk you through

  1. how to authentificate as a user via the API
  2. how to create an app to connect to the API
  3. how to use your app to query the Openclipart API

Get your user credentials

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
    }
  }
}

Store your user token

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)

Create your Openclipart API app

You can now create your Openclipart app via /api/v2/apps/createand 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.

Store your app credentials

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"

Let’s use the API !

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" \
    https://openclipart.org/api/v2@beta/search?q=water
{
  "success" : true,
  "status" : 200,
  "data" : {
      "files" : ...,
      "total_results":1961,
      "files_count":25
  }
}

Browse the doc for more…

Now head to https://openclipart.org/api-docs/ to access the complete documentation and start using it.