Iconik API Basics: Exploring Assets, Metadata, and Jobs
Managing multimedia assets presents both media companies and content creators with significant challenges. These include the complexities of organizing content storage solutions and ensuring seamless sharing and collaboration amidst a rapidly evolving media landscape. Iconik is a comprehensive cloud-based media management and collaboration tool designed to address these challenges by streamlining the organization, storage, and sharing of multimedia content.
The subsequent sections present basic Iconik concepts such as assets, metadata, and jobs, followed by an exploration of the basic Iconik API endpoints.
Understanding Key Iconik Concepts
Assets
An asset consists of one or more files and is automatically generated upon upload. It goes beyond a simple file reference, as it also encapsulates metadata, access rights, comments, and associations with other files and collections. These associations can vary, such as parent-child relationships where one asset acts as the parent to another, or collection relationships, which are automatically established for all collections an asset is added to.
Metadata
Iconik uses a proprietary metadata structure to provide enhanced user flexibility. This structure comprises three distinct levels:
- Metadata Field: Admins define each field, specifying its type and attributes. For example, a description might be an open text field with a specific character limit.
- Metadata Views: These views manage metadata fields as forms, allowing administrators to customize the display for different user groups. When multiple fields are present, administrators can choose to display select subsets to individual user groups.
- Metadata Categories: These categories determine where a view can be used within Iconik. Administrators can designate specific views for searches, collections, assets, and more.
Administrators have the authority to define which metadata users can access or utilize within the system.
Job
A job handles tasks that require time or multiple steps to complete. Each job is assigned a status, such as ‘Started’, ‘Finished’, or ‘Failed’. Moreover, a job can comprise subjobs, smaller tasks with their own status and history, which are reflected in the parent job.
Below are some examples of tasks commonly managed within jobs:
- Transcode: Converting a video, audio, or image file to create a preview
- Transfer: Copying a file from one location to another
- Delete: Removing an asset and its associated files
Using the API
Below is an overview of the main endpoints related to assets, metadata, and jobs, accompanied by Python example functions. Before using these functions with the REST API, users must first establish access by obtaining appropriate credentials from an admin or an admin account on the Iconik system.
All endpoints in the REST API share the same base URL to which calls (GET, POST, PATCH, PUT, DELETE) are directed, along with mandatory identification parameters specified in the header (App-ID and Auth-Token).
The base URL is to be included in the endpoints that will be presented later.
base_url = ‘https://app.iconik.io/API'
Below are instructions on how to recover the App-ID and the Auth-Token.
- Go to the admin panel and select Settings/Application Tokens from the side menu
- Create a new application or use an already existing
- Create a new authentication token and copy the app id from this page
Users are required to store this data in a secure way so it can be reused at a later time.
To facilitate the calls, a class can be created to manage the API base. Below is an example in Python:
import requests
# Define your Iconik credentials here
ICONIK_APP_ID_KEY = 'your_app_id'
ICONIK_AUTH_TOKEN_KEY = 'your_auth_token'
class IconikAPIService:
base_url = 'https://app.iconik.io/API'
app_header: dict
def __init__(self) -> None:
app_id = ICONIK_APP_ID_KEY
auth_token = ICONIK_AUTH_TOKEN_KEY
self.app_header = {
'App-ID': app_id,
'Auth-Token': auth_token,
}
def get(self, path: str):
return requests.get(f"{self.base_url}{path}", headers=self.app_header)
def post(self, path: str, body: dict):
return requests.post(f"{self.base_url}{path}", headers=self.app_header, json=body)
def patch(self, path: str, body: dict):
return requests.patch(f"{self.base_url}{path}", headers=self.app_header, json=body)
def put(self, path: str, body: dict):
return requests.put(f"{self.base_url}{path}", headers=self.app_header, json=body)
def delete(self, path: str):
return requests.delete(f"{self.base_url}{path}", headers=self.app_header)
GET
This section describes the main endpoints used to retrieve data.
To retrieve all assets:
/assets/v1/assets/
To retrieve a particular asset via its ID and its corresponding information:
/assets/v1/assets/{asset_id}/
Users can also append ?include_collections=true at the end of the endpoint. While not mandatory, it facilitates retrieval of the collections in which the assets are located. Additionally, appending ?include_users=true enables users to retrieve information about the users who have interacted with the asset.
Below is an example of this using the IconikAPIService class shown above:
def get_asset(asset_id: str, with_associated_data = True):
response = IconikAPIService().get(f"/assets/v1/assets/{asset_id}/?include_collections=true")
if response.status_code == 404:
return None
elif response.status_code != 200:
raise Exception(f"API Service Error: {response.reason}")
return response.json()
To retrieve metadata from an asset via its ID:
/metadata/v1/assets/{asset.id}/
To retrieve the files linked to an asset via its ID:
/files/v1/assets/{asset_id}/files
To retrieve an asset’s proxies via its ID:
/files/v1/assets/{asset_id}/proxies
Quick reminder ⇒ a proxy is a low-resolution version, used for preview, it’s faster to load, and less heavy but has a lower quality than the asset.
To retrieve a job:
/jobs/v1/jobs/{job_id}/
To retrieve the list of all metadata fields:
/metadata/v1/fields/
To retrieve information from a metadata field:
/metadata/v1/fields/{field_name}/
To retrieve the list of all metadata views:
/metadata/v1/fields/
Quick reminder ⇒ views are used to organize fields.
DELETE
This section presents the main endpoints used to delete data.
Deletes an asset using its ID:
/assets/v1/assets/{asset_id}/
Deletes a specific metadata field:
/metadata/v1/fields/{field_name}/
Deletes a job using its ID:
/jobs/v1/jobs/{job_id}/
Here is an example of a function using this endpoint:
def delete_job(job_id: str) -> bool:
response = IconikAPIService().delete(f"/jobs/v1/jobs/{job_id}/")
if response.status_code == 404:
return False
elif response.status_code != 204:
raise Exception(f"API Service Error: {response.reason}")
return True
POST
This section presents the main endpoints used to create new data.
Creates an asset:
/assets/v1/assets/
Parameter: title, type, status, is_online…
Associates a new proxy with an asset:
/files/v1/assets/{asset.id}/proxies/
Associates a new file with an asset:
/files/v1/assets/{asset.id}/files/
Associates a new fileset with an asset:
/files/v1/assets/{asset.id}/file_sets/
Quick reminder ⇒ a fileset is a collection of files.
Associates a new format with an asset:
/files/v1/assets/{asset.id}/formats/
Quick reminder ⇒ a format contains references to files or filesets.
Below is a diagram illustrating a single format asset with two components (video and audio). This asset is associated with a single fileset and corresponds to a single file.
Creates a new job:
/jobs/v1/jobs/
The title, status, and type of the new job must be specified at a minimum. Below is an example of a function that creates an ANALYZE job.
def create_job(self, asset_name: str):
response = self.iconik_api.post(
"/jobs/v1/jobs/",
{
'title': f"Create {asset_name} subclip",
'status': IconikJobStatus.READY,
'type': IconikJobType.ANALYZE,
}
)
if response.status_code == 404:
return None
elif response.status_code != 201:
raise Exception(f"API Service Error: {response.reason}")
return response.json()
To create a new metadata field:
/metadata/v1/fields/
PATCH
In this section, we will see the main endpoints to update already existing data.
Updates an asset:
/assets/v1/assets/{asset.id}
Updates a job:
/jobs/v1/jobs/{job.id}/
Updates a specific metadata field:
/metadata/v1/fields/{field_name}/
PUT
In this section, we will see the main endpoints to update already existing data.
Updates an asset:
/assets/v1/assets/{asset.id}
Updates a job:
/jobs/v1/jobs/{job.id}/
Updates a specific metadata field:
/metadata/v1/fields/{field_name}/
FAQ
What is the difference between put and patch ?
In Iconik API, put and patch have the same behavior: they update or completely replace an existing resource.
Why is there V1 in all the endpoints?
The API is versioned and depending on the versions the parameters can be very different so we have to specify the version we want to use.
Where to find more information?
More information can be found in Iconik’s official documentation: https://app.iconik.io/docs/api.html
About TrackIt
TrackIt is an Amazon Web Services Advanced Tier Services Partner specializing in cloud management, consulting, and software development solutions based in Marina del Rey, CA.
TrackIt specializes in Modern Software Development, DevOps, Infrastructure-As-Code, Serverless, CI/CD, and Containerization with specialized expertise in Media & Entertainment workflows including AWS Studio in the Cloud (SIC), Retail workflows, High-Performance Computing environments, and data storage.
In addition to providing cloud management, consulting, and modern software development services, TrackIt also provides an open-source AWS cost management tool that allows users to optimize their costs and resources on AWS.