Resource - Service Root Info

Every service is meant to support getting information about its functionalities in two ways:

  1. 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.

  2. 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:

  • languages: (optional) An array with the culture codes that are defined in the data model of the MediaCentral |* languages: (optional) An array with the culture codes that are defined in the data model of the MediaCentral \

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

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": "https://developer.avid.com/ctms/api/aa/linkrels/{rel}.html",
        "name": "aa",
        "templated": true
      },
      {
        "href": "https://developer.avid.com/ctms/api/ma/linkrels/{rel}.html",
        "name": "ma",
        "templated": true
      },
      {
        "href": "https://developer.avid.com/ctms/api/loc/linkrels/{rel}.html",
        "name": "loc",
        "templated": true
      },
      {
        "href": "https://developer.avid.com/ctms/api/search/linkrels/{rel}.html",
        "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"
          }
        ]
      }
    ]
  }
}