Quick Start - HAL (Hypertext Application Language)

The CTMS API uses HAL (Hypertext Application Language) as a convention for referencing resources via hypermedia links. This page gives only a brief overview of how to use HAL. You can find a more detailed explanation in Introduction to HAL.

HAL resources and links

HAL resources

A HAL resource is a JSON structure that contains the properties of the resource and two special properties:

  • _links: contains named links to other HAL resources, or to URIs that can be used to create, update, or modify resources.

  • _embedded: may contain linked HAL resources as embedded sub resources.

Example: a HAL resource that represents an Avid Production Management asset (abbreviated)

{
  "base": {
    "systemID": "ecbff1a8-0cf2-11ea-8d71-362b9e155667",
    "systemType": "avid-pmplus",
    "id": "060a2b340101010101010f0013-000000-000000009ec11cbc-060e2b347f7f-2a80",
    "type": "masterclip"
  },
  "common": {
    "name": "Prime time news show 2024-05-28",
    "creator": "Administrator",
    "editRate": "60000/1001",
    "dropframe": true,
    "durationTC": "00;30;00;02"
  },
  "_links": {
    "self": {
      "href": "https://host/..."
    },
    "aa:attributes": {
      "href": "https://host/..."
    },
    "aa:time-based": {
      "href": "https://host/..."
    },
    "aa:update-asset": {
      "href": "https://host/..."
    },
    "curies": [
      {
        "name": "aa",
        "href": "http://developer.avid.com/ctms/api/aa/linkrels/{rel}.html",
        "templated": true
      }
    ]
  }
}

The properties base and common are properties of the resource, here of an aa:asset resource for a masterclip. Every HAL resource type can have its own set of properties.

HAL links

The standard property _links contains a few standard links:

  • self: a HAL link that contains the URI of the current resource.

  • curies: defines templated links for the link prefixes that can be used to find the documentation for the links. The example defines the URI template http://developer.avid.com/ctms/api/aa/linkrels/{rel}.html for the prefix "aa". To see the documentation for a link, replace the URI template variable "rel" with the name of the link and open that page in a browser. Example: The documentation for the aa:update-asset link can be found on http://developer.avid.com/ctms/api/aa/linkrels/update-asset.html.

Additionally, each resource usually has a number of resource-specific links, like in the asset example above:

The property href of a link contains either a URI, or a URI template according to RFC-6570. URI templates are used for links that require URI parameters. See below for details. The HTTP method and body format, if needed, must be looked up in the documentation of the link.

Multi-links

A link can reference a single item as in the example above or it can reference an array of items. A collection, for example, can have a link to multiple items in the collection:

{
  "_links": {
    "loc:item": [
      {
        "href": "https://..."
      },
      {
        "href": "https://..."
      }
    ]
  }
}

Templated URIs

Templated HAL links are links that require one or more parameters. Templated links are marked with the property "templated": true.

Example:

{
  "_links": {
    "aa:asset-by-id": {
      "href": "https://.../{id}",
      "templated": true
    }
  }
}

In this case, the href property contains a RFC-6570 URI template.

A URI template is a URI-like string with URI template variables. The standard defines several patterns that allow using URI template variables for different aspects like path elements or query parameters of a URI.

Avid highly recommends using a library for the programming language of your choice that implements the full RFC standard.

The link aa:asset-by-id, for example, returns a URI template. To use it, you have to set the URI template variable id to the ID of the asset and expand the URI template.

Then, you can make an HTTP call to that URI to get or modify the resource. The link rel reference shows which HTTP verb to use, the format of the request body if required, possible URI query parameters, and information about the response for the different links.

Embedding resources with ?embed

To reduce the number of calls to get the information you need and to improve the performance, a caller can use the query parameter embed to ask the service to embed linked resources in the response of a call. The value of the embed query parameter is a comma-separated list of link names without the prefix(!). For example, when requesting the information about an asset, the caller can use the query parameter ?embed=attributes,time-based to ask the service to return the resources aa:attributes and aa:time-based as embedded sub resources.

The embed query parameter is only a hint for the service. A service or system might not support embedding a requested sub resource. The caller must expect that a requested sub resource is not returned, and fetch the sub resources using the corresponding link.

Embedded resources are returned as sub properties of the property _embedded in the response, with the name of the link as property name. Example of an asset with an embedded aa:attributes resource, requested with ?embed=attributes:

{
  "base": {
    "systemID": "E75274DF-BFE6-46CD-BA52-FB58CA0134F2",
    "systemType": "avid-pmplus",
    "id": "060a2b340101010101010f0013-000000-00c5dfe08ab0de80-060e2b347f7f-2a80",
    "type": "masterclip"
  },
  "common": {
    "name": "Visiting the Eiffel Tower in Paris"
  },
  "_links": {
    "aa:attributes": {
      "href": "https://..."
    }
  },
  "_embedded": {
    "aa:attributes": {
      "attributes": [
        {
          "name": "com.avid.workgroup.Property.System.Format",
          "value": "1080i/50",
          "type": "string",
          "value-labels": {
            "en": "1080i/50"
          }
        }
      ],
      "_links": {
        "self": {
          "href": "https://..."
        },
        "aa:update-attributes": {
          "href": "https://..."
        }
      }
    }
  }
}

 

Previous page: CTMS Registry

Up: Quick start

Next page: CTMS Resources