Using the CTMS Registry as Client

The CTMS registry collects the HAL resources provided by all the different CTMS services on the platform. A client can use the 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:

  1. The client must first authenticate against the platform. Please refer to the section Authentication for details.

  2. Get the service root of the CTMS Registry to obtain information about the operations the CTMS registry service provides.

  3. Get the full registry information to obtain information about the HAL resources of all services on the platform.

  4. 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://hostname/apis/avid.ctms.registry;version=0;realm=global

to get a resource enumerating links to the URLs pointing to functionalities provided by the CTMS registry. hostname 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://hostname/apis/avid.ctms.registry;version=0;realm=global/serviceroots{?rels}"
        },
        "self": {
            "href": "https://hostname/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://hostname/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:

{
    "_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://hostname/apis/avid.ctms.registry;version=0;realm=global/serviceroots"
        }
    },
	"systems":[
      {
	      "systemType": "interplay-mam",
		  "systemID":"BEEF",
	      "name": "MAM Server X Team",
		  "version": "5.9"
      },
	  {
          "systemType": "interplay-pam",
          "systemID": "3D6B717E-B061-451B-A991-9CBDEA634050",
          "name": "KL-SERENITY-PAM"
      }
    ],
    "resources": {
        "loc:folder-by-id": [
            {
                "href": "https://hostname/apis/avid.mam.assets.access;version=0;realm=myRealm/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=3D6B717E-B061-451B-A991-9CBDEA634050/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": "3D6B717E-B061-451B-A991-9CBDEA634050",
					}
				  ],
				  "templated": true
			}
        ], "search:simple-search": [
            {
                "href": "https://hostname/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://hostname/apis/avid.mam.assets.access;version=0;realm=myRealm/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://hostname/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://hostname/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://hostname/apis/avid.mam.assets.access;version=0;realm=myRealm/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://hostname/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://hostname/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://hostname/apis/avid.mam.assets.access;version=0;realm=myRealm/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://hostname/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://hostname/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.

The result is a HAL structure like this:

{
	"systems":[
      {
	      "systemType": "interplay-mam",
		  "systemID":"BEEF",
	      "name": "MAM Server X Team",
		  "version": "5.9"
      }
    ],
    "resources": {
        "aa:asset-by-id": [
            {
                "href": "https://hostname/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://hostname/apis/avid.mam.assets.access;version=0;realm=myRealm/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://hostname/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://hostname/apis/avid.mam.assets.access;version=0;realm=myRealm/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://hostname/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://hostname/apis/avid.mam.assets.access;version=0;realm=BEEF/locations/items/{id}" and "https://hostname/apis/avid.mam.assets.access;version=0;realm=myRealm/locations/items/{id}".

  • The elements in these arrays is 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.