CTMS - Handling assets

Overview

The CTMS API is a HAL API. The responses of REST calls contain links to other resources and other functionality of the API.

This page shows you how can navigate through the link structure of the API to get information about assets their attributes, and to update attributes of an asset.

Get an asset

Description

This operation queries the aa:asset resource for a given asset ID.

Input

System ID and asset ID.

Output

The aa:asset resource for the requested asset ID.

Steps

  1. Authenticate.

  2. Get CTMS Registry information or use cached information.

  3. Find the link rel aa:asset-by-id for the given system ID in the CTMS Registry.

    • Use a URI template library to set the URI template variable "id" to the asset id.

    • Call GET on the resolved URI to get the aa:asset resource.

Starting with the aa:asset resource, you can use the link rels in that resource to get additional information, or to update or delete the asset.

Get an asset with attributes and time-based annotation

Description

This operation gets the aa:asset resource for a given asset ID. Optionally, you can request an embedded aa:attributes resource with the custom attributes of the asset, and an embedded aa:time-based resource with time-based annotation.

Input

A system ID and an asset ID.

Output

The aa:asset resource with embedded aa:attributes resource.

Steps

  1. Authenticate.

  2. Get CTMS Registry information or use cached information.

  3. Find the link rel aa:asset-by-id for the given system ID in the CTMS Registry.

    • Use a URI template library to set the URI template variable "id" to the asset id.

    • To request an embedded aa:attributes resource: Add the query parameter embed=attributes.

      • Optional, but highly recommended: Add the query parameter attributes=a,b,c to request only the attributes you need, here a, b, and c. Without that, all attributes are returned, which is considerably slower and puts more pressure on the system.

    • To request an embedded aa:time-based resource: Add the query parameter embed=time-based.

      • Optional, but highly recommended: Add the query parameter layers=a,b,c to request only the layers of time-based annotation that you need, here a, b, and c. Without that, all layers are returned, which is considerably slower and puts more pressure on the system.

    • Call GET on the resolved URI to get the aa:asset resource with embedded aa:attributes and aa:time-based resources if requested.

Update attributes of an asset

Description

This operation updates attributes of an asset.

Input

A system ID, asset ID, and a list of attributes to change.

Output

none

Steps

  1. Get the aa:asset resource for the asset (see Get an asset).

  2. Find the link rel aa:update-asset in it. If the link rel is not present, you most probably don’t have the permissions to update the asset.

    • Call PATCH on the href with a JSON document with the information you want to update, in the same format as aa:asset, as request body. Common attributes are in the property common. Custom attributes are in an embedded aa:attributes resource.
      Example request body to set the common attribute "name" and the custom attribute "COMMENT":

      {
  "common": {
    "name": "A new name"
  },
  "_embedded": {
    "aa:attributes": {
      "attributes": [
        {
          "name": "COMMENT",
          "value": "A comment"
        }
      ]
    }
  }
}

Update time-based annoation

Description

This operation updates the time-based annotation of an asset.

Input

The system ID, asset ID, and a list of segments of one or more layers to update and create.

Output

The response is a JSON in the same format and in the same order for the segments as in the request body, but with the generated IDs for created segments.

Steps

  1. Get the aa:asset resource for the asset (see Get an asset).

  2. Find the link rel aa:update-time-based in it. If the link rel is not present, you most probably don’t have the permissions to update the time-based annotation.

    • The behavior of the update depends on the HTTP method you use:

      • PATCH creates and updates the given segments, and leaves segments that are not given untouched.

      • PUT creates and updates the given segments, and deletes segments that are not given.

    • The request body contains the segments to create and update. Example:

      {
  "layers": [
    {
      "name": "EDITORIAL_CONTENT",
      "segments": [
        {
          "id": "42",
          "start": 10,
          "duration": 20,
          "attributes": [
            {
              "name": "SEGMENT_DESCRIPTION",
              "value": "Lukas Podolski scores"
            }
          ]
        }
      ]
    }
  ]
}

    • If a segment ID is given and exists, the segment is updated. Otherwise it is created.

Delete segments of time-based annoation

Description

This operation deletes segments of the time-based annotation of an asset.

Input

The system ID, asset ID, and a filter for the segments to delete.

WARNING! The filter is crucial. If you leave it empty, the method deletes all segments of all layers!

Typical use cases:

  • layers=A&segmentids=25,26: Delete the segments 25 and 26 in the layer A.

  • layers=A: Delete all segments in layer A.

You should always use the layers query parameter to restrict deletion to a given layer!

  • For some system, like MC|PM for example, the segment ID is unique across all layers and sufficient to uniquely identify a segment of the asset.

  • However, for other systems, like MC|AM for example, the segment ID is only unique within a layer, but other layers can have segments with the same ID. If you only use segmentids=25,26, you will delete the segments 25 and 26 from all layers, which is in most cases not what you want to do.

Output

none

Steps

  1. Get the aa:asset resource for the asset (see Get an asset).

  2. Find the link rel aa:delete-time-based in it. If the link rel is not present, you most probably don’t have the permissions to delete time-based annotation.

    • Add a combination of URI query parameters to select the segments to delete:

      • layers=a,b,c to restrict deletion to the given layers.

      • segmentids=1,2,3 to restrict deletion to the given segment IDs.

    • Call DELETE on the resolved URI.

Delete an asset

Description

This operation deletes an asset.

Input

A system ID and an asset ID.

Output

none

Steps

  1. Get the aa:asset resource for the asset (see Get an asset).

  2. Find the link rel aa:delete-asset in it.
    If the link rel is not present, you most probably don’t have the permissions to delete the asset or the system doesn’t support deleting an asset this way.

    • Call DELETE on the href.

 

Previous page: Error Handling

Up: Quick start

Next page: Handling folder structure