CTMS - Handling the folder structure of a system

Overview

The CTMS API is a HAL API. The responses of REST calls contain links to other resources and other functionality of the API.

This page shows you how can use the CTMS API to navigate through the folder structure of a system.

All elements in the folder structure are represented as loc:item resources. A loc:item can be a folder, a reference to an asset, or both.

Folders and Collections

A folder is a loc:item resource that has a loc:collection link rel.

The loc:collection resource collects the items in the folder. It uses paging to keep the payload small even for folders with thousands of entries.

When querying the loc:item resource of a folder, the loc:collection resource is automatically embedded in the response, together with an embedded array of loc:item resources with the first page of items in the folder.

The root folder of the folder structure can be queried with the loc:root-item link rel.

Asset references

A loc:item resource can have a loc:referenced-object link rel that references the aa:asset resource of an asset. When querying the loc:item directly, the loc:referenced-object resource is embedded automatically.

Finding references to an asset

If you have the aa:asset resource of an asset in your hand, you can use the loc:referencing-items link rel to find all references to this asset in the entire folder hierarchy.

Get the root folder

Description

This operation queries the loc:item resource that represents the root folder of the system.

Input

System ID.

Output

The loc:item resource for the root folder.

Steps

  1. Authenticate.

  2. Get CTMS Registry information or use cached information.

  3. Find the link rel loc:root-item for the given system ID in the CTMS Registry.

    • Call GET on the resolved URI to get the loc:item resource of the root folder. It contains an embedded loc:collection resource with the collection of items in the folder, which in turn contains an embedded array of loc:item resources that represent the first page of items in the root folder.

  4. Use the next link to iterate through the pages. See Paging for details.

Get a folder or asset reference by its location ID

Description

This operation queries the loc:item resource for a given location ID.

Input

System ID and location ID.

Output

The loc:item resource.

Steps

  1. Authenticate.

  2. Get CTMS Registry information or use cached information.

  3. Find the link rel loc:item-by-id for the given system ID in the CTMS Registry.

    • Use a URI template library to set the URI template variable "id" to the location ID.

    • Call GET on the resolved URI to get the loc:item resource.

Create a folder

Description

This operation creates a new sub folder.

Input

A system ID, the location ID of an existing folder, and the name of the new folder.

Output

The loc:item resource of the new folder.

Steps

  1. Get the loc:item resource for the existing folder (see Get a folder or asset reference by its location ID).

  2. Call HTTP POST on the loc:create-folder link rel with a request body like this:

    {
    "common": {
        "name": "A new name"
    }
}

    The response is the loc:item resource of the new folder.

 

Previous page: Handling assets

Up: Quick start

Next page: Handling taxonomies