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:

What we did there was to call the API 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:

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:

• Curl
• Postman
• Paw

Creating an asset

It's time to use the API for creation of resources in Iconik, not just query and see what's already there. The asset is the base container for all media that lives in Iconik and a good place to start. To create an asset using the API you can follow the example below. As previously it is good to keep track of the returned id for later use.

An answer similiar to this will be returned: { "analyze_status": "N/A", "archive_status": "NOT_ARCHIVED", "created_by_user": "fbc97f28-eb6f-11ea-9915-c2e3aed96f38", "date_created": "2020-09-01T12:57:42.818545+00:00", "date_deleted": null, "date_modified": "2020-09-01T12:57:42.818565+00:00", "deleted_by_user": null, "external_id": "string", "id": "b947e9da-ec52-11ea-b571-0af7c14f78f9", "is_online": false, "status": "ACTIVE", "title": "string", "type": "ASSET", "versions": [ { "analyze_status": "N/A", "archive_status": "NOT_ARCHIVED", "created_by_user": "fbc97f28-eb6f-11ea-9915-c2e3aed96f38", "date_created": "2020-09-01T12:57:42.822357+00:00", "id": "b9485f96-ec52-11ea-b571-0af7c14f78f9", "is_online": false, "status": "ACTIVE", "transcribe_status": "N/A" } ] }

Finding an asset

Let's use the search endpoint to find our recently created asset. To search among assets and sort with most recent first, try this:

An answer similiar to this will be returned: { "facets": null, "first_url": "/v1/search/?page=1&per_page=10", "last_url": "/v1/search/?page=1&per_page=10", "next_url": null, "objects": [ { "_highlight": { "title": [ "[[mark]]string[[/mark]]" ] }, "analyze_status": "N/A", "archive_status": "NOT_ARCHIVED", "created_by_user": "fbc97f28-eb6f-11ea-9915-c2e3aed96f38", "date_created": "2020-09-01T12:57:42.818000", "date_deleted": null, "date_modified": "2020-09-01T12:57:42.818000", "deleted_by_user": null, "external_id": "string", "id": "b947e9da-ec52-11ea-b571-0af7c14f78f9", "is_online": false, "media_type": "unknown", "object_type": "assets", "permissions": [ "write", "change-acl", "delete", "read" ], "status": "ACTIVE", "system_domain_id": "1297c8b6-3563-11e7-adf1-6c4008b85488", "title": "string", "type": "ASSET", "versions": [ { "analyze_status": "N/A", "archive_status": "NOT_ARCHIVED", "created_by_user": "fbc97f28-eb6f-11ea-9915-c2e3aed96f38", "date_created": "2020-09-01T12:57:42.822000", "id": "b9485f96-ec52-11ea-b571-0af7c14f78f9", "is_online": false, "status": "ACTIVE", "transcribe_status": "N/A" } ], "versions_number": 1 }, ...

Uploading an image

By uploading an image the entire data model is touched upon. In this example we will

1. Create an asset
2. Associate a file format and file set
3. Choose the default storage location
4. Start a upload job
5. Actually uploading the file
6. Tie all loose ends together
7. Clean up

The complete example follows below.

Metadata

This section will guide you through the process of creating a custom view and applying it to an asset. Creating a custom view:

That call will return a json with a field labeled id. To be able to use the view in the web interface that id must be added to the default list. Start by getting all ids in the default list:

You will get a json with a field view_ids that looks a bit like this "view_ids": [ "98e2bca2-504a-11e7-aebc-0a580a000282", "d34e6f1c-d60f-11e9-a8cb-ee0a854c7179", "13c634de-97a4-11e7-bcd0-0a580a000434", "edc29974-ebe3-11e8-81e2-0a580a000433", "07c56980-6cb8-11e7-adee-0a580a000216", ... and to that list you add the id from the previous step. Now you use the extended list as input to your amended category:

You can now use the view as metadata for assets in the web GUI or update it using the API as below:

Webhooks

To set up a web hook that forwards changes of assets you can do like this:

The POST request will return something similar to:

{ "id": "e5f48626-f0d7-11ea-8a46-eecfc44550a5", "status": "ENABLED", "date_created": "2020-09-07T07:01:05.486423+00:00", "event_type": "assets", "url": "https://iconik-logger.herokuapp.com/", "operation": null, "object_id": null, "realm": null, "date_modified": "2020-09-07T07:01:05.486423+00:00" }

In the example above the endpoint https://iconik-logger.herokuapp.com/ was set up to receive POST requests as the webhook and dumnp the message body to the logs. The message sent by the webhook will look similar to this:

{ "system_domain_id": "YOUR-SYSTEM-DOMAIN-ID", "object_id": "6ce31914-eddf-11ea-b571-0af7c14f78f9", "realm": "metadata", "operation": "update", "data": { "version_id": "6ce381b0-eddf-11ea-b571-0af7c14f78f9", "metadata_values": { "first_name": { "field_values": [ { "value": "Poaters" } ], "date_created": "2020-09-07T06:45:41.979412+00:00" } }, "object_type": "assets", "object_id": "6ce31914-eddf-11ea-b571-0af7c14f78f9" }, "request_id": "90762250227cb0d5e0a7a37b806b3a04", "event_type": "assets" }

And in that response you can see that the goats name has been changed to Poaters. Now the service can act accordingly.

Rate Limiting

The iconik APIs use rate limiting to prevent individual users to negatively impact other users of the system. The rate limiting is done per authenticated user and application token, so you should use separate application tokens for each application you integrate with iconik to prevent them from interfering with each other.

Each API response includes a http header RateLimit-Remaining which contains the number of requests remaining until the rate limiting will start blocking requests. The iconik rate limiting uses a Leaky Bucket Algorithm where we allow 50 requests per second sustained or 1000 requests over any 20 second period.

Once the rate limit has been reached iconik will respond with a http response 429 Too Many Requests telling you to slow down the response. If you encounter such a response you should back off and retry the request after a few seconds.

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!