Every service is meant to support getting information about its functionalities in two ways:
-
Requesting the service root via upstream, i.e. the http endpoint of the service itself, e.g. https://host/apis/avid.mam.assets.access;version=0;realm=0f7a6bfc-0376-4d24-b8af-9bb9492bc859/ will respond with a Service Root resource.
-
Getting the service root via the bus operation getServiceRoot will respond with a slightly downgraded version of a Service Root resource.
Generally, Service Root is a resource that defines the capabilities of the service and provides links to functionalities of the service.
A CTMS service must implement the bus operation getServiceRoot mentioned in 2., in order to be compliant with the CTMS Registry service. Only services that implement the getServiceRoot are automatically registered.
Properties of Service Root
A service must return the following properties to be compliant with the CTMS Registry service:
| Property | Type | Description |
|---|---|---|
systems |
array |
Contains information about the systems that are known by this service. The value is an array of JSON objects. Each JSON object describes one system. See system description for details. |
service |
service struct, optional |
Description of the service. See service description for details. |
resources |
array |
Resource descriptions. See resources descriptions for details. |
_links |
map, optional |
A map of link relations. See links for details. |
For a full example, see Example.
System Description ("systems" Property)
| Property | Type | Description |
|---|---|---|
systemType |
string |
Type of the system. Examples: "interplay-mam", "interplay-pam". |
systemID |
string |
ID of the system on the platform. |
description |
string, optional |
Human-readable description of the resource. |
name |
string |
Display name of the system. |
systemTypeName |
string, optional |
Acts as label for the system type. |
host |
string, optional |
The system’s host name. |
origin |
string, optional |
If the system was injected from a remote CTMS Registry in a Multi-Site setup, this property carries the URL of the remote CTMS Registry’s endpoint (this information stems from the RSR). |
remoteAvailability |
boolean, optional |
The system declares itself to be available remotely, i.e. to be regarded by the CTMS Registry in a Multi-Site setup. If not given, the system is not available remotely (false). |
version |
string, optional |
Version of the system. |
properties |
name-value list, optional |
Additional properties. The values each can represent any valid JSON data. The following properties are currently in use, but there can be any number of additional properties:
|
Example
{
"systems": [
{
"systemType": "interplay-mam",
"systemID": "0f7a6bfc-0376-4d24-b8af-9bb9492bc859",
"name": "Example MC | Asset Management installation",
"systemTypeName": "Asset Management",
"description": "Example installation for demo purposes",
"version": "5.9",
"origin": "https://remotebox",
"remoteAvailability": true,
"properties": {
"languages": [ "en", "fr", "de", "en-UK" ],
"preferredThumbnailWidth": 176,
"aString" : "text",
"aNumber" : 3.14,
"anObject" : {"foo": 1, "bar" : "bar"},
"emptyArray": [],
"emptyObject": {},
"emptyString": "",
"booleanTrue": true,
"booleanFalse": false,
"nothing": null
}
}
]
}
Service Description ("service" Property)
The "service" property should include descriptive information about the service.
| Property | Type | Description |
|---|---|---|
name |
string, optional |
Name of the service |
version |
string, optional |
Version |
description |
string, optional |
Human-readable description |
id |
string, optional |
ID of the service |
properties |
map, optional |
Name-value list of additional properties. The values each can represent any valid JSON data. |
Example
{
"service": {
"name": "MAMAssetsCTC",
"version": "6.0.0.0",
"description": "MediaCentral | Asset Management Connectivity Toolkit Connector",
"id": "MAMAssetsCTC_1",
"properties": {
"anArray": [ "1stItem", "2ndItem", "3rdItem" ],
"aString" : "text",
"aNumber" : 3.14,
"anObject" : {"foo": 1, "bar" : "bar"},
"emptyArray": [],
"emptyObject": {},
"emptyString": "",
"booleanTrue": true,
"booleanFalse": false,
"nothing": null
}
},
…
}
Resources Description ("resources" Property)
The Service Root must include a list of all link rels that shall be visible in the CTMS Registry. I.e. a service declares in the "resources" property, which functionality should be published via the CTMS Registry. Keep in mind, that one can still request the full functionality a service provides via direct REST calls, but only registering functionality allows to look them up via the CTMS Registry gaining a lot of valuable features. The "resources" property is a map of link rels to link rel descriptions having additional information. For each link rel, the following properties can be returned:
| Property | Type | Description |
|---|---|---|
href |
string |
The URL of the HAL resource. |
description |
string, optional |
Human-readable description of the resource. |
templated |
boolean, optional |
true if the href is a templated URI, false, null or missing if not. |
templateParams |
array, optional |
If href is a templated URI, this property must describe all template parameters. See URI template parameters for details. |
systems |
array |
List of systems on the platform that can be accessed using this link rel. See system references for details. |
properties |
map, optional |
Name-value list of additional properties for the resource. The values each can represent any valid JSON data. |
URI Template Parameters
templateParams is a map from template parameter names to descriptions.
| Property | Type | Description |
|---|---|---|
description |
string, optional |
Human-readable description. |
type |
string |
Type, e.g. "string" |
Example (abbreviated)
{
"service": {
…
},
"resources": {
"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": "0f7a6bfc-0376-4d24-b8af-9bb9492bc859"
}
]
}
],
…
}
…
}
System References ("resources.systems" Property)
If a resource is supposed to deal with one or more specific systems on the platform, it should return a list of all those systems in the property systems. If a service can be used universally on the platform, it should not return the systems property.
Some link rels may require a given list of systems. For example, aa:assets or aa:asset-by-id deal with assets of specific systems on the platform. A client usually knows type and ID of the system that owns an asset. To identify the correct resource, each platform service that provides an aa:assets must specify the systems it can handle.
| Property | Type | Description |
|---|---|---|
systemType |
string |
Type of the system. Examples: "interplay-mam", "interplay-pam". |
systemID |
string |
ID of the system on the platform. |
The "systems" top-level property should include descriptive information about the systems that are referenced. See system description for details.
Example of a resource that describes one specific system (abbreviated)
{
"systems": { … },
"service": { … },
"resources": {
"aa:asset-by-id": [
{
"href": "https://host/…/{id}",
"description": "get an asset by id",
"templated": true,
"templateParams": {
"id": {
"description": "the id of the asset in question",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID": "0f7a6bfc-0376-4d24-b8af-9bb9492bc859"
}
]
}
]
}
}
Links ("_links" Property)
The services of the CTMS API may contain the following links:
| Link rel | Verb | Description |
|---|---|---|
aa:assets |
GET |
Returns a HAL resource that contains links to get and manipulate assets. See aa:assets for details. |
loc:locations |
GET |
Returns a HAL resource that contains links to get and manipulate a folder structure for a system. See loc:locations for details. |
settings:settings |
GET |
Returns a HAL resource that contains links to query and manipulate the settings of a system. See settings:settings for details. |
ia:queues |
GET |
Returns a HAL resource that contains links to get and manipulate MediaCentral Newsroom Management queues. See ia:queues for details. |
ia:monitors |
GET |
Returns a HAL resource that contains links to get and manipulate MediaCentral Newsroom Management monitors. See ia:monitors for details. |
ia:system |
GET |
Returns a HAL resource that contains links to get and manipulate MediaCentral Newsroom Management system resources like forms, templates, print styles and so on. See ia:system for details. |
ia:users |
GET |
Returns a HAL resource that contains links to get and manipulate MediaCentral Newsroom Management users. See ia:users for details. |
All linked resources can and should be embedded (_embedded property) into the service root info to avoid unnecessary calls to the backend.
Example
The following full example for a service’s service root, shows a service that provides exactly two resources, designated by the link rels loc:item-by-id and aa:asset-by-id for a MediaCentral Asset Management system:
Example: Full service root information
{
"systems": [
{
"systemType": "interplay-mam",
"systemID": "0f7a6bfc-0376-4d24-b8af-9bb9492bc859",
"name": "MC | Asset Management Server",
"host": "mam-hostname",
"version": "5.9"
}
],
"service": {
"name": "MAMAssetsCTC",
"version": "6.0.0.0",
"description": "MediaCentral | Asset Management Connectivity Toolkit Connector",
"id": "MAMAssetsCTC_1",
"properties": {}
},
"resources": {
"loc:item-by-id": [
{
"href": "https://host/…",
"description": "get an item by id",
"templateParams": {
"id": {
"description": "the id of the item in question",
"type": "string"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID": "0f7a6bfc-0376-4d24-b8af-9bb9492bc859"
}
]
}
],
"aa:asset-by-id": [
{
"href": "https://host/…",
"description": "get an asset by id",
"templateParams": {
"id": {
"description": "the id of the asset",
"type": "string"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID": "0f7a6bfc-0376-4d24-b8af-9bb9492bc859"
}
]
}
]
},
"_links": {
"curies": [
{
"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/locations/{rel}",
"name": "loc",
"templated": true
},
{
"href": "http://services.avid.com/apis/search/{rel}",
"name": "search",
"templated": true
}
],
"loc:locations": {
"href": "https://host/…",
"title": "interplay-mam"
},
"aa:assets": {
"href": "https://host/…",
"title": "interplay-mam"
},
"ma:assets": {
"href": "https://host/…",
"title": "interplay-mam"
}
},
"_embedded": {
"aa:assets": {
"_links": {
"self": {
"href": "https://host/…"
},
"aa:asset-by-id": {
"href": "https://host/…",
"templated": true
},
…
}
},
"loc:locations": {
"_links": {
"self": {
"href": "https://host/…"
},
"loc:root-item": {
"href": "https://host/…"
},
…
}
}
}
}
Enabling Registry Support in a Service
As mentioned at the top of this document, the bus operation getServiceRoot must be implemented, which has to respond with a slightly downgraded version of a Service Root resource. Basically everything specified above holds true for the bus operation getServiceRoot. There is only one difference: the resources' endpoints are no full URLs, but have placeholders for the scheme ({proto}) and the authority ({host}), which are filled by the CTMS Registry using the context of the REST request as it is provided by Upstream.
Example: Full Service root info
{
"service": {
"name": "MAMAssetsCTC",
"version": "6.0.0.0",
"description": "MediaCentral | Asset Management Connectivity Toolkit Connector",
"host": "mam-hostname",
"id": "MAMAssetsCTC_1",
"properties": {}
},
"resources": {
"loc:item-by-id": [
{
"href": "{proto}://{host}/apis/…/{id}",
"description": "get an item by id",
"templateParams": {
"id": {
"description": "the id of the item in question",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID": "0f7a6bfc-0376-4d24-b8af-9bb9492bc859",
"name": "MC | Asset Management Server",
"version": "5.9"
}
]
}
],
"loc:folder-by-id": [
{
"href": "{proto}://{host}/apis/…/{id}",
"description": "get a folder by id",
"templateParams": {
"id": {
"description": "the id of the folder in question",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID": "0f7a6bfc-0376-4d24-b8af-9bb9492bc859",
"name": "MC | Asset Management Server",
"version": "5.9"
}
]
}
],
"aa:asset-by-id": [
{
"href": "{proto}://{host}/apis/…/{id}",
"description": "get an asset by id",
"templateParams": {
"id": {
"description": "the id of the asset in question",
"type": "int"
}
},
"systems": [
{
"systemType": "interplay-mam",
"systemID": "0f7a6bfc-0376-4d24-b8af-9bb9492bc859",
"name": "MC | Asset Management Server",
"version": "5.9"
}
]
}
]
}
}