A CTMS Session using the CTMS Registry

The aim of this document is to give developers information how to use the CTMS Registry to put working with CTMS APIs into effect. For this example the simple search was used to show how things work.

  • Precondition: authorization was done via an HTTP basic authorization string, which can be obtained from Avid. The authorization provides an openid token, which is to be used as bearer token for upcoming communication with upstream in HTTP "Authorization" headers.

  • Request the CTMS Registry:

GET https://upstream/apis/avid.ctms.registry/serviceroots
Accept: application/hal+json
Authorization: Bearer MAGIC

  • Get the 'search:simple-search' resources from the CTMS Registry response. 'search:simple-search' can potentially be provided by n CTMS-compatible service instances, therefor the result is a list of 'search:simple-search' resources:

var simpleSearchResources = jsonPath("resources..'search:simple-search'");

  • For this example let’s pick the very first 'search:simple-search' resource. (In reality a resource provided by a specific systemId might be picked.):

var simpleSearchResource = simpleSearchResources[0];

  • Each resource returned from the CTMS Registry provides a URI template, which we need to build the effective URL to request the search. So let’s get the URI templates of the 'search:simple-search' resource we have in our hands now:

var simpleSearchUriTemplate = simpleSearchResource.jsonPath("..href");

  • The returned simpleSearchUriTemplate looks like this:

https://upstream/apis/avid.mam.assets.access;realm=BEEF;version=0/searches/simple?search={search}{&offset,limit,sort}

  • Now we have to fill in the placeholders, which are declared in braces in the URI template. In this case we only need to fill in the parameter {search}, the parameters {&offset,limit,sort} can be ignored right now. {search} contains the search expression. Using a library to handle URI templates is recommended, because it cares for correct replacement as well as correct URL-encoding of inserted arguments. We’ll insert the search expression '*', which specifies a search for all assets:

var simpleSearchUri = simpleUriSearchTemplate.set('search', '*').expand();

  • The expanded URI template, which makes the effective URI to be requested looks like this:

https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/searches/simple?search=%2A

As can be seen, the '*' character was properly URL-encoded to %2A.

  • Next, we’ll Request simpleSearchUri to get the search result, it’ll respond with the first page of results (assets), which contains, e.g., 50 assets per page for MediaCentral Asset Management:

GET https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/searches/simple?search=%2A
Accept: application/hal+json
Authorization: Bearer MAGIC

  • Having the search results in the response, we can iterate over the retrieved assets:

var assets = simplSearchResult.jsonPath("..'_embedded'..'aa:asset'");
for (var asset : assets) {
    var id = asset.jsonPath("..base.id");
    var name = asset.jsonPath("..common.name");
}

  • If the search result is made up of more than one page, there will exist a link "next":

var hrefToNextPage = simplSearchResult.jsonPath("_links.next.href");

  • If hrefToNextPage contains a valid URI (= has a value), we can use this URI to request the next page:

GET https://upstream/apis/avid.mam.assets.access;realm=BEEF/searches/simple?search=%2A&offset=50&limit=50
Accept: application/hal+json
Authorization: Bearer MAGIC

As can be seen, the (query) parameters offset and limit are set in this URI. – Those act as an "anchor" to mark the iteration state of the paging procedure.

  • Postcondition: Logout from the platform

Concrete examples of how this procedure works was cast in code, and can be found in the CTMS Client examples.