The CTMS Registry collects the HAL resources provided by all the different CTMS services on the platform. A client can use the CTMS Registry to navigate through the APIs of the entire platform. A second use case is the selection of one out of many similar links in order to access very specific functionality. For example, a client that knows the ID tuple of an asset (system type, system ID, asset type, and asset ID) can select an aa:asset-by-id link for a service that provides access to the system that owns the asset.
A client can access the CTMS Registry using REST calls:
-
The client must first authenticate against the platform. Please refer to the section Authentication for details.
-
Get the service root of the CTMS Registry to obtain information about the operations the CTMS Registry service provides.
-
Get the full registry information to obtain information about the HAL resources of all services on the platform.
-
Query specific link relations to obtain information about a given link rel for all services on the platform that support that link rel.
Get the service root of the CTMS Registry
After the client has authenticated against the platform, it can use GET on the URL
https://upstream/apis/avid.ctms.registry;version=0;realm=globalto get a resource enumerating links to the URLs pointing to functionalities provided by the CTMS Registry. upstream is the DNS name or IP address of the server running the Avid Platform infrastructure. The result is a HAL structure like this:
{
"_links": {
"curies": [
{
"name": "registry",
"templated": true,
"href": "http://services.avid.com/apis/registry/{rel}"
}
], "registry:serviceroots": {
"href": "https://upstream/apis/avid.ctms.registry;version=0;realm=global/serviceroots{?rels}"
},
"self": {
"href": "https://upstream/apis/avid.ctms.registry;version=0;realm=global"
}
}
}Get the full registry information
The client can then continue GET-requesting the URL behind the link rel "registry:serviceroots", e.g.
https://upstream/apis/avid.ctms.registry;version=0;realm=global/serviceroots
to get all information stored in the CTMS Registry. The result is a HAL structure like this:
Example: HAL structure
{
"_links": {
"curies": [
{
"href": "http://services.avid.com/apis/locations/{rel}",
"name": "loc",
"templated": true
},
{
"href": "http://services.avid.com/apis/assets/{rel}",
"name": "aa",
"templated": true
},
{
"href": "http://services.avid.com/apis/mam/assets/{rel}",
"name": "ma",
"templated": true
},
{
"href": "http://services.avid.com/apis/search/{rel}",
"name": "search",
"templated": true
},
{
"href": "http://services.avid.com/apis/orchestration/{rel}",
"name": "orchestration",
"templated": true
}
], "self": {
"href": "https://upstream/apis/avid.ctms.registry;version=0;realm=global/serviceroots"
}
},
"systems":[
{
"systemType": "interplay-mam",
"systemID":"BEEF",
"name": "AM Server X Team",
"version": "5.9"
},
{
"systemType": "interplay-pam",
"systemID": "BEEF2",
"name": "PM System of Team K"
}
],
"resources": {
"loc:folder-by-id": [
{
"href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/locations/folders/{id}",
"description": "get a folder by id",
"templateParams": {
"id": {
"description": "the id of the folder in question",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID":"BEEF"
}
]
}, {
"href": "{proto}://{host}/apis/avid.pam;version=2;realm=BEEF2/locations/folders{/id}{?offset,limit,attributes,embed,filter,sort}",
"description": "get folder by id",
"templateParams": {
"filter": {
"description": "the filter expression",
"type": "string"
},
"offset": {
"description": "the paging offset",
"type": "int"
},
"limit": {
"description": "the paging limit",
"type": "int"
},
"attributes": {
"description": "the attributes",
"type": "string"
},
"id": {
"description": "the id of the folder in question",
"type": "string"
},
"embed": {
"description": "the embed flag",
"type": "string"
},
"sort": {
"description": "the sorting expression",
"type": "string"
}
},
"systems": [
{
"systemType": "interplay-pam",
"systemID": "BEEF2"
}
],
"templated": true
}
], "search:simple-search": [
{
"href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/searches/simple?search={search}{&offset,limit,sort}",
"description": "get the result of a simple search",
"templateParams": {
"search": {
"description": "the simple search expression",
"type": "string"
},
"offset": {
"description": "the paging offset",
"type": "int"
},
"limit": {
"description": "the paging limit",
"type": "int"
},
"sort": {
"description": "controls the sort order of the search results",
"type": "string"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID":"BEEF"
}
]
},
{
"href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/searches/simple?search={search}{&offset,limit,sort}",
"description": "get the result of a simple search",
"templateParams": {
"search": {
"description": "the simple search expression",
"type": "string"
},
"offset": {
"description": "the paging offset",
"type": "int"
},
"limit": {
"description": "the paging limit",
"type": "int"
},
"sort": {
"description": "controls the sort order of the search results",
"type": "string"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID":"BEEF"
}
]
}
], "orchestration:process-query": [
{
"href": "https://upstream/apis/avid.orchestration.ctc;version=0;realm=BEEF/process-queries/{id}{?offset,limit,sort}",
"description": "query a process' status by id",
"templateParams": {
"id": {
"description": "the id of the process in question",
"type": "int"
},
"offset": {
"description": "the paging offset",
"type": "int"
},
"limit": {
"description": "the paging limit",
"type": "int"
},
"sort": {
"description": "controls the sort order of the search results",
"type": "string"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID":"BEEF"
}
]
}
], "aa:asset-by-id": [
{
"href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/assets/{id}",
"description": "get an asset by id",
"templateParams": {
"id": {
"description": "the id of the asset in question",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID":"BEEF"
}
]
},
{
"href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/assets/{id}",
"description": "get an asset by id",
"templateParams": {
"id": {
"description": "the id of the asset in question",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID":"BEEF"
}
]
}
], "orchestration:update-process": [
{
"href": "https://upstream/apis/avid.orchestration.ctc;version=0;realm=BEEF/processes/{id}",
"description": "update a process by id",
"templateParams": {
"id": {
"description": "the id of the process to update",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID":"BEEF"
}
]
}
], "loc:item-by-id": [
{
"href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/locations/items/{id}",
"description": "get an item by id",
"templateParams": {
"id": {
"description": "the id of the item in question",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID":"BEEF"
}
]
},
{
"href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/locations/items/{id}",
"description": "get an item by id",
"templateParams": {
"id": {
"description": "the id of the item in question",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID":"BEEF"
}
]
}
], "orchestration:process": [
{
"href": "https://upstream/apis/avid.orchestration.ctc;version=0;realm=BEEF/processes/{id}",
"description": "get a process by id",
"templateParams": {
"id": {
"description": "the id of the process in question",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID":"BEEF"
}
]
}
]
}
}
This is a HAL resource that combines the link rels of the service root information of all registered services on the platform, including the curie definitions.
-
The property resources contains the information about all top-level link rels on the platform, which have been published by the registered services.
-
Every sub property of resources represents one link rel. For example: "aa:asset-by-id".
-
For each link rel, there is an array of resource objects associated, which represent endpoints of all the services, which support the link rel’s functionality. Technically, the CTMS Registry calls the bus method getServiceRoot for all registered bus services and collects/aggregates the returned HAL resources under the link rels. For a detailed description of the properties of those resource objects, see resources and service in the Service Root documentation.
Query specific link relations
After the client has authenticated against the platform, it can use GET on the URI
https://upstream/apis/avid.ctms.registry;version=0;realm=global/serviceroots{?rels}
to get the information about all services on the platform that implement the given link rels.
-
upstream is the DNS name or IP address of the server running the Avid Platform infrastructure.
-
rels is a comma-separated list of link rels. Note that it is required to encode the ":" with %3A. Example: https://upstream/apis/avid.ctms.registry;version=0;realm=global/serviceroots?rels=aa%3Aasset-by-id,loc%3Aitem-by-id to query the link rels aa:asset-by-id and loc:item-by-id.
The result is a HAL structure like this:
Example: HAL structure
{
"systems":[
{
"systemType": "interplay-mam",
"systemID":"BEEF",
"name": "AM Server X Team",
"version": "5.9"
}
],
"resources": {
"aa:asset-by-id": [
{
"href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/assets/{id}",
"description": "get an asset by id",
"templateParams": {
"id": {
"description": "the id of the asset in question",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID":"BEEF"
}
]
},
{
"href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/assets/{id}",
"description": "get an asset by id",
"templateParams": {
"id": {
"description": "the id of the asset in question",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID":"BEEF"
}
]
}
], "loc:item-by-id": [
{
"href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/locations/items/{id}",
"description": "get an item by id",
"templateParams": {
"id": {
"description": "the id of the item in question",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID":"BEEF"
}
]
},
{
"href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/locations/items/{id}",
"description": "get an item by id",
"templateParams": {
"id": {
"description": "the id of the item in question",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID":"BEEF"
}
]
}
]
},
"_links": {
"curies": [
{
"href": "http://services.avid.com/apis/locations/{rel}",
"name": "loc",
"templated": true
},
{
"href": "http://services.avid.com/apis/assets/{rel}",
"name": "aa",
"templated": true
},
{
"href": "http://services.avid.com/apis/mam/assets/{rel}",
"name": "ma",
"templated": true
},
{
"href": "http://services.avid.com/apis/search/{rel}",
"name": "search",
"templated": true
}
], "self": {
"href": "https://upstream/apis/avid.ctms.registry;version=0;realm=global/serviceroots?rels=aa%3Aasset-by-id,loc%3Aitem-by-id"
}
}
}
-
The property resources contains the information about all links rels that were queried as properties, here: aa:asset-by-id and loc:item-by-id.
-
With an individual link rel property an array is associated, which lists the endpoints, which support the requested link rel on the platform, e.g. aa:asset-by-id is supported by the endpoints "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/locations/items/{id}" and "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/locations/items/{id}".
-
The elements in these arrays are aggregated from CTMS compliant services supporting those link rels and contain a lot more information about links apart from the bare endpoint. For a detailed description of the properties contained in the link information elements, see resources and service in the Service Root documentation.
Query Systems in a Multi-Site Setup
The client can also get more specific information about systems in a Multi-Site setup.
https://upstream/apis/avid.ctms.registry;version=0;realm=global/serviceroots?site-local=true
https://upstream/apis/avid.ctms.registry;version=0;realm=global/serviceroots?remote-availability=true
-
site-local can be set to true to explicitly exclude all links to remote systems.
-
remote-availability can be set to true to only include links to systems, which are remotely available.