CTMS - Query the CTMS Registry

The CTMS Registry

The CTMS API is a HAL API. The responses of REST calls contain links to other resources and other functionality of the API. The page Understanding HAL-based APIs tells you all you need to know about HAL.

The entry point to the API is the CTMS Registry. It contains a core set of links to the functionality of the CTMS API. Most of them reutrn HAL resources that again contain links to other resources or actions. You can navigate thorugh the entire API by following links. The only hard-coded link (apart from the link for authentication) should be the one for the CTMS Registry.

The page The correct way to resolve a link to a resource contains detailed information on how to use the CTMS Registry.

Query the CTMS Registry

  1. Authenticate to get an access token.

  2. Query the CTMS Registry with a GET request to https://cloudux-host/ctms-registry/v1 where cloudux-host is the fully-qualified host name of the CloudUX system, with the access token in the Authorization header or the avidAccessToken cookie.
    The result is a JSON document with a core set of links to the functionality of the CTMS API and information about the systems that are connected to the CloudUX system.
    Example showing the aa:asset-by-id link rel (abbreviated):

    {
  "resources": {
    "aa:asset-by-id": [
      {
        "href": "https://.../{id}",
        "systems": [
          {
            "systemType": "interplay-mam",
            "systemID": "FDFD806C-ADA5-441C-9256-ADFF3E91C849"
          }
        ],
        "templated": true
      }
    ]
  },
  "systems": [
    {
      "systemType": "interplay-mam",
      "systemID": "FDFD806C-ADA5-441C-9256-ADFF3E91C849",
      "name": "MC|AM test system",
      "systemTypeName": "Asset Management",
      "version": "8.4",
      "host": "somehost.domain"
    }
  ]
}

    The CTMS Registry returns information about the systems in CloudUX and links to the functionality of the systems:

    JSON property Description

    systems

    The systems (like Avid Production Management, MediaCentral | Asset Management, MediaCentral | Production Management, and more) that are available in the CloudUX installation.

    resources

    Links to several CTMS resources like assets and folders. See Links in the CTMS Registry for an overview.

See Using the CTMS Registry as a Client for details.

The information in the CTMS Registry is usually very stable and changes only if a system or service is added or shuts down. Avid highly recommends caching the information and updating it only about every minute.

Find link rel in CTMS Registry

For link rels that are registered in the CTMS Registry (see Link rels in CTMS Registry) for a given system, you can find the URL directly in the CTMS Registry information.

In the property resources, find the link rel that you need, e.g. aa:asset-by-id. The value is an array. Find the entry where systems contains the system type and system ID of the system that you want to access. The property href contains the URI you need next.

In Javascript, you can get the href value like this:

function findLinkRelForSystem(ctmsResponse, linkRel, systemId) {
    return ctmsResponse.resources
        ?.[linkRel]
        ?.find(r => r.systems
            ?.find(system => system?.systemID==systemId))
        ?.href
}

var href = findLinkRelForSystem(ctmsResponse,"aa:asset-by-id", "someSystemId")

In some cases, the URI is a templated URI (RFC-6570) and you have to replace the URI template variables accordingly. See Templated URIs for details.

Link rels in "root" resources

Some link rels are not available directly in the CTMS Registry but are only available in so-called "root resources" like aa:assets, loc:locations, or taxonomies:taxonomies. In this case, you must find the link rel like this:

  1. Find the link rel for the root resource like, for example, aa:assets for the system in the CTMS Registry, as shown above.

  2. Use GET on the href to get the root resource, here aa:assets.

  3. The response is a HAL resource. Find the link rel you are interested in in the HAL response.

 

Previous page: Authentication

Up: Quick start

Next page: HAL