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 full registry information to obtain information about the HAL resources of all services on the platform.
-
Query information for a given system to obtain information about the given link rel for a given system.
-
Query specific link relations to obtain information about a given link rel for all services on the platform that support that link rel.
Compatibility
CloudUX 2023.12 and newer
The recommended URL for the CTMS Registry is
https://host/ctms-registry/v1
-
"host" is the DNS name or IP address of the CloudUX system.
The URL was introduced in CloudUX 2023.11 and is recommended when using CloudUX 2023.11 or higher and will be used in the following chapters.
CloudUX 2023.7 and older
If your code must be able to run against CloudUX 2023.7 or older, you must use the following URL instead:
https://host/apis/avid.ctms.registry;version=0;realm=global
-
"host" is the DNS name or IP address of the CloudUX system.
To ensure compatibility, this old URL will continue working in newer versions for the foreseeable future.
Get the full registry information
After the client has authenticated against the platform, it can use GET on the URL
https://host/ctms-registry/v1
to get all information stored in the CTMS Registry.
-
"host" is the DNS name or IP address of the CloudUX system.
The result is a HAL structure like this:
Example: HAL structure
{
"_links": {
"curies": [
{
"href": "https://developer.avid.com/ctms/api/loc/linkrels/{rel}.html",
"name": "loc",
"templated": true
},
{
"href": "https://developer.avid.com/ctms/api/aa/linkrels/{rel}.html",
"name": "aa",
"templated": true
}
],
"self": {
"href": "https://host/…"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID": "7B7E2886",
"name": "AM Burlington"
},
{
"systemType": "interplay-pam",
"systemID": "PM-TEST",
"name": "PM Munich"
}
],
"resources": {
"loc:root-item": [
{
"href": "https://host/…",
"description": "get the root folder",
"systems": [
{
"systemType": "interplay-mam",
"systemID": "7B7E2886"
}
]
},
{
"href": "https://host/…",
"description": "get the root folder",
"systems": [
{
"systemType": "interplay-pam",
"systemID": "PM-TEST"
}
]
}
],
"aa:asset-by-id": [
{
"href": "https://host/…/{id}",
"description": "get an asset by id",
"templateParams": {
"id": {
"description": "the id of the asset in question",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID": "7B7E2886"
}
]
},
{
"href": "https://host/…/{id}",
"description": "get an asset by id",
"templateParams": {
"id": {
"description": "the id of the asset in question",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-pam",
"systemID": "PM-TEST"
}
]
}
]
}
}
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.
| Property | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
systems |
Information about the systems that are connected to the CloudUX site. For a detailed description, see System description in the Service Root documentation. |
||||||||||||
resources |
Information about all top-level link rels on the platform. Each sub property of resources represents a link rel. The value is an array of links for the different systems for which the link rel is available. Example for the link rel aa:asset-by-id: Here, the array for the link rel aa:asset-by-id has two entries:
Each entry in the array for a link rel has the following properties:
For a detailed description, see resources in the Service Root documentation. |
Query information for a given system
After the client has authenticated against the platform, it can use GET on the URI
https://host/ctms-registry/v1?systemid=someSystemId
to get the information about all services and link rels for the given system ID.
-
"host" is the DNS name or IP address of the CloudUX system.
-
"systemid" is the requested system ID.
The result is a HAL structure similar to the one above with the full information but restricted to the requested link rels.
Query specific link relations
After the client has authenticated against the platform, it can use GET on the URI
https://host/ctms-registry/v1?rels=aa%3Aasset-by-id,loc%3Aroot-item
to get the information about all services on the platform that implement the given link rels.
-
"host" is the DNS name or IP address of the CloudUX system.
-
"rels" is a comma-separated list of link rels.
The link rels should be percent-encoded using the encoding rules for URL query parameters. Here, the ":" is encoded as "%3A". The example above queries the link rels aa:asset-by-id and loc:root-item.
The result is a HAL structure similar to the one above with the full information but restricted to the requested link rels.
You can combine the query parameters rels and systemid to request only the given link rels and only for the given system:
https://host/ctms-registry/v1?systemid=someSystemId&rels=aa%3Aasset-by-id,loc%3Aroot-item
Query systems in a multi-site setup
The client can also get more specific information about systems in a multi-site setup.
https://host/ctms-registry/v1?site-local=true
https://host/ctms-registry/v1?remote-availability=true
-
"host" is the DNS name or IP address of the CloudUX system.
-
"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.