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 handle taxonomies.

A taxonomy is a a controlled list of entries that can be assigned, for example, as value to an attribute of an asset. Typical examples:

A flat list of entries. Example: MC|AM legal lists.
A hierarchy of entries, organized as a tree. Example: MC|AM thesauri.

The entries can have localized labels.

The link rels taxonomies:entries, which gets the top-level entries, and taxonomies:child-entries, which gets the child entries of an entry for hierarchical taxonomies, both use paging to limit the size of the response payload. You can use the prev and next links to iterate through the result pages, or request a specific range using the URI query parameters offset and limit.

Get the list of taxonomies

Description	This operation lists the taxonomies of a system.
Input	System ID.
Output	The taxonomies:taxonomy-list resource.
Steps	Authenticate. Get CTMS Registry information or use cached information. Find the link rel taxonomies:taxonomies for the given system ID in the CTMS Registry. Add the query parameter embed=taxonomy-list. Call `GET` on the resolved URI to get the taxonomies:taxonomies resource. It contains an embedded taxonomies:taxonomy-list resource with an array of taxonomies:taxonomy link rels that reference the taxonomies of the system.

Description

This operation lists the taxonomies of a system.

Input

System ID.

Output

The taxonomies:taxonomy-list resource.

Steps

Authenticate.
Get CTMS Registry information or use cached information.
Find the link rel taxonomies:taxonomies for the given system ID in the CTMS Registry.
- Add the query parameter embed=taxonomy-list.
- Call GET on the resolved URI to get the taxonomies:taxonomies resource.
- It contains an embedded taxonomies:taxonomy-list resource with an array of taxonomies:taxonomy link rels that reference the taxonomies of the system.

Get a taxonomy by ID

Description	This operation queries the information about a taxonomy and returns the first page of top-level entries.
Input	System ID and taxonomy ID.
Output	The taxonomies:taxonomy resource.
Steps	Authenticate. Get CTMS Registry information or use cached information. Find the link rel taxonomies:taxonomy-by-taxonomyid for the given system ID in the CTMS Registry. Use a URI template library to set the URI template variable "taxonomyid" to the taxonomy ID. Recommended: add URI query parameter lang=en to request the labels in the given language. Optional: add URI query parameter embed=entries to request embedding the first page of top-level entries. Call `GET` on the resolved URI to get the taxonomies:taxonomy resource. If "embed=entries" was set: The result contains an embedded taxonomies:entries resource with the first page of entries on the top-level of the taxonomy. Use the next link to iterate through the pages. See Paging for details.

Description

This operation queries the information about a taxonomy and returns the first page of top-level entries.

Input

System ID and taxonomy ID.

Output

The taxonomies:taxonomy resource.

Steps

Authenticate.
Get CTMS Registry information or use cached information.
Find the link rel taxonomies:taxonomy-by-taxonomyid for the given system ID in the CTMS Registry.
- Use a URI template library to set the URI template variable "taxonomyid" to the taxonomy ID.
- Recommended: add URI query parameter lang=en to request the labels in the given language.
- Optional: add URI query parameter embed=entries to request embedding the first page of top-level entries.
- Call GET on the resolved URI to get the taxonomies:taxonomy resource.
If "embed=entries" was set:
- The result contains an embedded taxonomies:entries resource with the first page of entries on the top-level of the taxonomy.
- Use the next link to iterate through the pages. See Paging for details.

Get a taxonomy entry by ID

Description	This operation gets an entry of a taxonomy.
Input	A system ID, the ID of the taxonomy and the ID of the taxonomy entry.
Output	The taxonomies:entry resource.
Steps	Authenticate. Get CTMS Registry information or use cached information. Find the link rel taxonomies:entry-by-taxonomyid-and-entryid for the given system ID in the CTMS Registry. Use a URI template library to set the URI template variable "taxonomyid" to the taxonomy ID. Use a URI template library to set the URI template variable "entryid" to the entry ID. Recommended: add URI query parameter lang=en to request the labels in the given language. Call `GET` on the resolved URI to get the taxonomies:entry resource of the entry.

Description

This operation gets an entry of a taxonomy.

Input

A system ID, the ID of the taxonomy and the ID of the taxonomy entry.

Output

The taxonomies:entry resource.

Steps

Authenticate.
Get CTMS Registry information or use cached information.
Find the link rel taxonomies:entry-by-taxonomyid-and-entryid for the given system ID in the CTMS Registry.
- Use a URI template library to set the URI template variable "taxonomyid" to the taxonomy ID.
- Use a URI template library to set the URI template variable "entryid" to the entry ID.
- Recommended: add URI query parameter lang=en to request the labels in the given language.
- Call GET on the resolved URI to get the taxonomies:entry resource of the entry.

Previous page: Folder structure

Up: Quick start