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"
    }
  ]
}

See Using the CTMS Registry as a Client for details.

You should cache the information for a small amount of time.

System IDs

Systems that are connected to CloudUX are identified by a system ID. You can find information about all known systems in the property systems in the CTMS Registry response.

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.

Find link rel in root resource

Some link rels are not available directly in the CTMS Registry but are only available in "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.

Find link rel anywhere

In a lot of cases, it is good practise to first try finding a link rel in the CTMS Registry (see Find link rel in CTMS Registry). If it is not available there, find the link rel in the corresponding root resource (see Find link rel in root resource).

 

Previous page: Query the CTMS Registry

Up: Quick start

Next page: Error handling