API Overview

Our guide to the REST APIs of iconik

Setup your access

You will need to have either an admin account or an admin to give you the correct credentials on the iconik system before you can start developing against our REST API.

You will also need a user account that you want to run the REST API as. This user account should be a user on the system that has access to the entities that you wish to work with. Heres how:

  1. Login to iconik with a user that has administrative rights
  2. If you don't already have a user that you want to run the REST API with, create a new user at this point.
  3. Navigate to the admin interface, and click on settings on the left-hand navigation bar and a sub-menu will open.
  4. Choose Application Tokens, or click here to open a window to take you to the admin page for the iconik system this document is being served from.
  5. Enter a new Application name describing what you will be using the REST API for. i.e. Testing REST API
  6. Select the username of a user that you wish to run the API as.
  7. Click Add
  8. An App-ID and a Token will be generated. Copy the App-ID and the token somewhere safe such as a password manager.
  9. This is the only time that we will display the token and it can never be retrieved again so copy it somewhere safe.

First steps

If you have followed getting started you should have an API-ID and a token. You can use those with a REST client to start using the API.

You will need a REST client that you can change the headers in, some examples are shown on the right. Curl is available on most platforms, and the following example will be shown here.

The following is a curl command you can execute from a terminal which would retrieve the list of storages. Make sure to replace the Auth-Token and App-ID with your own, and change the link from app.iconik.io if you are using another iconik system:

curl -X GET --header 'Content-Type: application/json' --header 'Auth-Token: your-token-here' --header 'App-ID: your-app-id-here' 'https://app.iconik.io/API/files/v1/storages/'

What we did there was use Curl with our authentication parameters, asking iconik for the list of storages, using version 1 of the API ( v1 ) from the files resource. The list should be presented back in JSON formatting

If you execute the above you should get a JSON payload with details about the storage, which should look similar to:

{ "facets": { "method": { "buckets": [ { "doc_count": 3, "key": "GCS" } ], "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0 }, "purpose": { "buckets": [ { "doc_count": 1, "key": "FILES" }, { "doc_count": 1, "key": "KEYFRAMES" }, { "doc_count": 1, "key": "PROXIES" } ], "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0 }, "scanner_status": { "buckets": [ { "doc_count": 3, "key": "INACTIVE" } ], "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0 }, "status": { "buckets": [ { "doc_count": 3, "key": "ACTIVE" } ], "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0 } }, "first_url": "/v1/storages/?page=1&per_page=10", "last_url": "/v1/storages/?page=1&per_page=10", "next_url": null, "objects": [ { "id": "4c3f6dfa-d524-11e7-8dd9-0a580a3c0236", "method": "GCS", "name": "iconik-proxies-gcs", "purpose": "PROXIES", "scanner_status": "INACTIVE", "settings": { "bucket": "iconik-eu-proxies", "delete": true, "json_key": "", "path": "c23b39f0-d520-11d7-ba26-0a580a3c0019", "project": "iconik-test", "read": true, "scan": false, "write": true }, "status": "ACTIVE", "status_message": null }, { "id": "4de72810-d524-11e7-ad1f-0a580a3c0236", "method": "GCS", "name": "iconik-keyframes-gcs", "purpose": "KEYFRAMES", "scanner_status": "INACTIVE", "settings": { "bucket": "iconik-eu-keyframes", "delete": true, "json_key": "", "path": "c23b39f0-d520-11d7-ba26-0a580a3c0019", "project": "iconik-test", "read": true, "scan": false, "write": true }, "status": "ACTIVE", "status_message": null }, { "id": "4aa7aca8-d524-11e7-95b7-0a580a3c0236", "method": "GCS", "name": "iconik-files-gcs", "purpose": "FILES", "scanner_status": "INACTIVE", "settings": { "bucket": "iconik-eu-files", "delete": true, "json_key": "", "path": "c23b39f0-d520-11d7-ba26-0a580a3c0019", "project": "iconik-test", "read": true, "scan": false, "write": true }, "status": "ACTIVE", "status_message": null } ], "page": 1, "pages": 1, "per_page": 10, "prev_url": null, "total": 3 }%

As you can see it can be fairly long and is designed to be parsed by machine, but it's still readable. There is also some standard information that is used when listing resources:

"first_url": "/v1/storages/?page=1&per_page=10", "last_url": "/v1/storages/?page=1&per_page=10", "next_url": null, "page": 1, "pages": 1, "per_page": 10, "prev_url": null, "total": 3

This details the number of resources in total, the number on this “page”, the number per page and how many pages to help you paginate through longer lists.

The id for each listed resource is also important, as for most resources we can use the ID to then get further information about that resource, for instance a query like:

curl -X GET --header 'Content-Type: application/json' --header 'Auth-Token: your-token-here' --header 'App-ID: your-app-id-here' 'https://app.iconik.io/API/files/v1/storages/4aa7aca8-d524-11e7-95b7-0a580a3c0236/'

Would give us information about the resource 4aa7aca8-d524-11e7-95b7-0a580a3c0236 as called by /API/files/v1/storages/4aa7aca8-d524-11e7-95b7-0a580a3c0236/ on the server.

Recommend REST Clients

This is our un-official recommendations for testing our REST API:

Next Steps

If you have followed the above please feel free to try this:

  1. Try doing the above using PostMan or another GUI, then try using a programming language.
  2. Look at the API reference documentation. This will give you a complete view of all the API endpoints for iconik, plus more information on what to expect.
  3. Checkout how iconik can call your server or service using Webhooks as and when events happen within iconik
  4. View our best practices on keeping your application and your information stored on iconik secure by following our Security guidelines
  5. Let us know when you build something awesome!