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:
The four values correspond to the ID values in the common object API of MediaCentral. |
common |
An optional property with the following, optional sub properties:
|
Concrete asset types, like, for example, a MediaCentral Asset Management 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:
https://upstream/apis/avid.mam.assets.access;version=0;realm=9f5a031a-7b00-4f26-a031-81a2d23a0ce3/locations/items/132.278?attributes=commentThis might result in something like this:
{
"base": {
"id": "132.278",
"type": "folder-item",
"systemType": "interplay-mam",
"systemID": "9f5a031a-7b00-4f26-a031-81a2d23a0ce3"
},
"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.
Folder structure
The platform API supports displaying a folder structure. This part of the API was designed with the LocationsUI API of MediaCentral 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");
}
}