Resource - Service Root

The service root resource is the entry point to the entire CTMS functionality of an individual CTMS service. It contains:

  • Information about the service itself, like, for example, the name and the version number.

  • Information about the systems that are available via the service.

  • A list of all resources provided by the service. Resources are the link rels that shall be available directly in the CTMS Registry.

The href property in the resources must use the placeholders {proto} and {host} to enable the CTMS Registry to generate different URLs in various scenarios. Example:

{
  "resources": {
    "aa:asset-by-id": [
      {
        "href": "{proto}://{host}/apis/.../{id}",
        ...
      }
    ]
  }
}

A CTMS-compliant service has two options to be included in the CTMS Registry:

  • It can implement a bus method named getServiceRoot that returns a top-level HAL resource with links to the functionality that the service provides.

  • If the service is running as Kubernetes service on the CloudUX platform, it can implement a REST endpoint that returns the Service Root resource and is detected by means of Kubernetes annotations in the Kubernetes Ingress configuration.

Properties

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.

Property "systems"

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

Property "service"

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 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
         }
     },
     …​
}

Property "resources"

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. templateParams is a map with the template parameter name as key and a JSON object with the following sub properties as value:

Sub property

Description

description

Human-readable description (optional)

type

Type, e.g. "string"

Example:

"templateParams": {
  "id": {
    "description": "the id of the asset in question",
    "type": "string"
  }
}

systems

array

List of the systems on the platform that can be accessed using this link rel via the service. Each entry has two sub properties:

Sub property Description

systemType

Type of the system. Examples: "interplay-mam", "interplay-pam".

systemID

ID of the system on the platform.

Example:

"systems": [
  {
    "systemType": "interplay-mam",
    "systemID": "0f7a6bfc-0376-4d24-b8af-9bb9492bc859"
  }
]

If a service can be used universally on the platform, it should not return the systems property.

The "systems" top-level property should include descriptive information about the systems that are referenced.

properties

map, optional

Name-value list of additional properties for the resource. The values can represent any valid JSON data.

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": "Asset Management",
      "host": "mam-hostname",
      "version": "8.4"
    }
  ],
  "service": {
    "name": "MAMAssetsCTC",
    "version": "10.3.0.81",
    "description": "MediaCentral | Asset Management Connectivity Toolkit Connector",
    "id": "MAMAssetsCTC_1",
    "properties": {}
  },
  "resources": {
    "loc:item-by-id": [
      {
        "href": "{proto}://{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": "{proto}://{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": { …​ }
}