CT-MS API Documentation

Handling of Assets

The Avid Platform API will provide an interface to query and modify different kinds of assets. Assets can be video objects, audio objects, but also pure Meta data objects, or even folders of a folder structure. It is even possible that an asset can even be used in multiple different contexts. For example, an asset can act both as a video asset and as a folder in a folder structure.

In the platform API, we use something like a class hierarchy to handle the differences and commonalities between the different asset types. Conceptually, all asset types "derive" from a base type common object. In client libraries for the different programming languages the types are in deed implemented as a class hierarchy. However, the API itself is a HAL interface, consisting of HAL resources. And there is no class hierarchy between resources. On the HAL level, the hierarchy is realized by defining common sets of properties and links.

Common Object

A common object is a HAL resource with the following properties:

Property Description

base

A property with the following sub properties:

  • systemType

  • systemID

  • type

  • id

The four values correspond to the ID values in the common object API of Media Central.

common

An optional property with the following, optional sub properties:

  • name

  • creator

  • created

  • modifier

  • modified

  • …​

Concrete asset types, like, for example, a MAM asset, can have additional properties and links.

Dealing with dynamic Common Attributes

Some API calls allow to specify the query parameter "attributes", which accepts a comma separated list of system-specific attribute names. The specified attribute values will be filled and added to the property "common" as additional properties. - If a specified attribute name is not known to the requested resource in its specific system type, it will be just be not included into "common". Whether a service type handles attribute names case insensitive or not is not defined. E.g. we could call the link behind "loc:item-by-id" on a avid.mam.assets.access system type to get the item resource including the "comment" attribute like so:

Requesting loc:item-by-id
https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/locations/items/132.278?attributes=comment

This might result in something like this:

Response with Attributes
{
"base": {
        "id": "132.278",
        "type": "folder-item",
        "systemType": "interplay-mam",
        "systemID": "BEEF"
    },
    "common": {
        "name": "My new video",
        "creator": "Administrator",
        "created": "2016-06-09T16:24:23.027+02:00",
        "modifier": "Administrator",
        "modified": "2016-06-09T16:24:23.027+02:00",
        "comment": "Deja vu!"
},
    "_links": {...}
...
}

As can be seen "name", "creator", "created", "modifier" and "modified" are present in the response as default-set of attributes, if the system type avid.mam.assets.access is requested that way. The service type avid.mam.assets.access does not support additional attributes on folders.

Profiles

If a HAL resource contains an embedded asset, then the embedded asset is returned as common object. This is especially important when parsing a HAL resource as a client (at least in C#), because in this case the code can parse only the common part as a common object and can’t directly downcast to a more specific asset type. We use profiles according to RFC 6906 to transport information about the specific type of a common object. The HAL resource has a link "profile" that contains an identifier for the specific type. Example:

TODO: What’s here*

Profile indicating the specific type

A HAL resource can have multiple profiles to indicate that it behaves according to multiple specialized types.

Folder structure

The platform API supports displaying a folder structure. This part of the API was designed with the LocationsUI API of Media Central in mind, but some details are different.

HAL Resources for a Folder Structure

If a system supports displaying a folder structure, the service root information contains a link loc:root-item. A GET on the link’s href returns the root item of the folder structure. An item in the folder structure can act as:

  • folder

  • reference to a common object

  • or both

An item that acts as a folder has a link loc:collection, pointing to a collection of items in the folder. The items in the folder can again be sub folders or asset references or both. The collection MUST also be returned as embedded resource of the folder.

An item that acts as reference to common object has a link loc:referenced-object, pointing to the associated object. The associated object CAN be returned embedded as embedded resource of the folder.

See Resource - loc:item for details about items.

Displaying the Folder Structure of a System

The following pseudo-code shows how to display the folder structure of a system:

// Part 1: display the root node
function showRootNode()
{
    serviceInfo = GET service root info   // should be cached
    rootItem = GET(serviceInfo.Link("loc:root-item"));
    bool isExpandable = rootItem.ContainsLink("loc:collection");
    // create a node in the tree that displays the name of the root folder, but also stores Href of the rootItem, because we need it later:

    var rootTreeNode = new Treenode(rootItem.Common.Name, rootItem.Href,isExpandable);
 treeView.Node.Add( rootTreeNode );       // add the root node to the
folder tree }
// Part 2: the user expands an item acting as folder
function expandFolder(treeNode)
{
    var href = treeNode.Href;
in the tree
    var item = GET(treeNode.Href);
about the item
// get the stored HRef of the item
  // get the latest information
    do {
  foreach(var subItem in item.Collection.Items) { // iterate through all
sub items of the expanded item, Collection is embedded collection
resource
   bool isExpandable = subItem.ContainsLink("loc:collection");        //
item is a folder => is expandable
   var subTreeNode = new TreeNode(subItem.Common.Name, subItem.Href,
isExpandable); // create new tree node for the sub item
         treeNode.Nodes.Add(subTreeNode);      // add below the expanded
node }
  item = FollowLink(item, "next");   // get next page
 } while(item != null);
}
// Part 3: the user clicks on an item in the tree (can be an inner node
or a leaf node!)
function displayAsset(treeNode)
   {
    var href = treeNode.Href;       // get the stored HRef of the item
in the tree
    var item = GET(treeNode.Href);    // get the latest information
about the item
 if(item.ContainsLink("loc:referenced-object"))  // the node references
an asset
 {
  var referencedAsset =
item.GetEmbeddedResource("loc:referenced-object");
  if(referencedAsset == null) {
   referencedAsset = GET(item.Link("loc:referenced-object").Href);
  }
  display(referencedAsset);   // do something with the asset
 } else {
ShowMessage("This node doesn't reference an asset");
 }
}

Elements of the API