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. See Authentication for details.

  2. Get the Service Root of the CTMS Registry returns information about the operations the CTMS registry can provide.

  3. Complete Information: returns information about the HAL resources of all services on the platform.

  4. Query Specific Link Relations: returns information about a given link rel for all services on the platform that support that link rel.

  5. Redirect: allows a client to make a call to a given link rel with a given set of additional filter criteria. The CTMS registry services resolves the URI, including URI template replacement and responds with a redirect (HTTP status code 307) to the real service URI.

No. 5 is not implemented yet!

Get the Service Root of the CTMS Registry

After the client has authenticated against the platform, it can use GET on the URL

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

Complete Information

The client can then continue GET-requesting the URL behind the link rel "registry:serviceroots", e.g.

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"
        }
    },
    "resources": {
        "loc:folder-by-id": [
            {
                "href": "https://hostname/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",
                        "name": "MAM Server X Team",
                        "version": "5.9"
                    }
                ]
            },
            {
                "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",
                        "name": "MAM Server X Team",
                        "version": "5.9"
                    }
                ]
            }
        ], "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",
                        "name": "MAM Server X Team",
                        "version": "5.9"
                    }
                ]
            },
            {
                "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",
                        "name": "MAM Server X Team",
                        "version": "5.9"
                    }
                ]
            }
        ], "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",
                        "name": "MAM Server X Team",
                        "version": "5.9"
                    }
                ]
            }
        ], "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",
                        "name": "MAM Server X Team",
                        "version": "5.9"
                    }
                ]
            },
            {
                "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",
                        "name": "MAM Server X Team",
                        "version": "5.9"
                    }
                ]
            }
        ], "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",
                        "name": "MAM Server X Team",
                        "version": "5.9"
                    }
                ]
            }
        ], "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",
                        "name": "MAM Server X Team",
                        "version": "5.9"
                    }
                ]
            },
            {
                "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",
                        "name": "MAM Server X Team",
                        "version": "5.9"
                    }
                ]
            }
        ], "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",
                        "name": "MAM Server X Team",
                        "version": "5.9"
                    }
                ]
            }
        ]
    }
}

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

to get the information about all services on the platform that implement the given link rels.

The result is a HAL structure like this:

{
    "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",
                        "name": "MAM Server X Team",
                        "version": "5.9"
                    }
                ]
            },
            {
                "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",
                        "name": "MAM Server X Team",
                        "version": "5.9"
                    }
                ]
            }
        ], "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",
                        "name": "MAM Server X Team",
                        "version": "5.9"
                    }
                ]
            },
            {
                "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",
                        "name": "MAM Server X Team",
                        "version": "5.9"
                    }
                ]
            }
        ]
    },
    "_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.

A graphics showing the aggregation of info from the individual service roots to the response of the service registry would be helpful.

Redirect

not implemented yet!
What about POST, DELETE, and others? Could be solved with status code *307 Temporary Redirect* (see https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).

After the client has authenticated against the platform, it can use all HTTP verbs on the URI

with additional query parameters that select a link of that link relation. Example:

This call looks at all links for the aa:asset-by-id link relation. It will take the first link that supports the system with system type "interplay-mam" and system ID "12345". The href of that link is treated as a URI template. The URI template parameter "id" is replaced with "abcde". The resulting URI is returned as redirect with HTTP code 307 (temporary redirect) which is supposed to cause the client to do a redirect with the same verb (and hopefully body and HTTP headers) as the call to CTMS registry.

If no link fulfils the given criteria, the CTMS registry returns 404 Not found.

Valid query parameters:

Query parameter Description

system.systemType

filter by system type

system.systemID

filter by system ID

system.property.X

filter by system property X

property.X

filter by link property X

All other query parameters are used as URI templates for the href of the selected link.