Collection-to-collection relations¶

New in version 24.1.

This section describes non hierarchical relations between collections. The relation can be used to find simply loosely related collections.

Type of relations
Managing collection relations

Type of relations ¶

Relations

can be directional or undirectional. In a directional relation, one collection is the source and another collection is the target. In an undirectional relation, the two collections are treated equally
are manually built using the API
have metadata as key-value pairs. One key-value pair which is always present is the type key, which describes the reason of the relationship.

Managing collection relations ¶

List all collection relations ¶

GET /collection/(collection-id)/relation¶

Returns a list of relations that matches the search criteria. Collection id can be an Identifiers, that is libraries can be used.

Query Parameters:	direction (string) – `U` - Only return undirectional relations where `collection-id` is part of. `S` - Only return directional relations where `collection-id` is the source collection. `T` - Only return directional relations where `collection-id` is the target collection. `D` - Only return directional relations where `collection-id` is the source or target collection. `A` (default) - Return all relations that `collection-id` is a part of.
Status Codes:	400 – An invalid direction has been specified. 404 – Could not find the collection identified by `collection-id`.
Produces:	application/xml, application/json – CollectionRelationListDocument. text/plain – CR LF -delimited list of Tabbed tuples of relation id, relation URI, direction type (`U`, `D`), relation type, and source id, target id.
Role:	_relation_read

In addition, extra query parameters of the form key=value can be added, to only return relations that matches the key-value pair(s).

Create an collection relation ¶

POST /collection/(collection-id)/relation/(id)¶

Generates a new relation between the two collections with the given ids, collection-id and id, with the given parameters.

Query Parameters:	direction (string) – Required. `U` - Set the direction of the relation as undirectional. `S` - Set the direction as `collection-id` being the source and `id` being the target. `T` - Set the direction as `id` being the source and `collection-id` being the target. allowDuplicate (boolean) – `true` (default) - Allow duplicate relations. `false` - Avoid adding duplicate relations.
Status Codes:	400 Bad request – Both `collection-id` and `id` identifies the same collection, or the direction is invalid. 404 Not found – Could not find the collection identified by `collection-id` or `id`.
Produces:	application/xml, application/json – CollectionRelationDocument.
Role:	_collection_relation_write

In addition, extra query parameters of the form key=value can be added, to set metadata of the collection-to-collection relation.

Delete all relations between two collections ¶

DELETE /collection/(collection-id)/relation/(id)¶

Deletes the relations with the specified direction or all relations between collection-id and id.

Query Parameters:	direction (string) – `A` - This is the default value. Deletes all relations between `collection-id` and `id`. `U` - Deletes only the relations with the direction as undirectional. `S` - Deletes only the relations where `collection-id` is the source and `id` is the target. `T` - Deletes only the relations where `id` is the source and `collection-id` is the target.
Status Codes:	200 OK – The collection relation is deleted.
Role:	_collection_relation_write

Delete all relations to a specific collection ¶

DELETE /collection/(collection-id)/relation¶

Deletes the relations with the specified direction or all relations.

Query Parameters:	direction (string) – `A` - This is the default value. Deletes all relations `collection-id` is involved in. `U` - Deletes only the relations with the direction as undirectional. `S` - Deletes only the relations where `collection-id` is the source. `T` - Deletes only the relations where `collection-id` is the target.
Status Codes:	200 OK – The collection relation is deleted.
Role:	_collection_relation_write

Create multiple collection relations ¶

POST /collection/relation¶

Generates multiple relations at once. Each relation has a source and a target, and the direction can take the value U, if not set it generates a directional relation from source to target.

Query Parameters:	allowDuplicate (boolean) – `true` (default) - Allow duplicate relations. `false` - Avoid adding duplicate relations.
Status Codes:	400 Bad request – Both `source` and `target` identifies the same collection, or the direction is invalid. 404 Not found – Could not collection the collection identified by `source` or `target`.
Accepts:	application/xml, application/json – CollectionRelationListDocument
Produces:	application/xml, application/json – CollectionRelationListDocument
Role:	_collection_relation__write

For example:

<?xml version="1.0"?>
<CollectionRelationListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <relation>
    <direction>
      <source>VX-1</source>
      <target>VX-2</target>
    </direction>
  </relation>
  <relation>
    <direction>
      <source>VX-1</source>
      <target>VX-3</target>
    </direction>
  </relation>
  <relation>
      <direction type="U">
        <source>VX-4</source>
        <target>VX-5</target>
      </direction>
   </relation>
</CollectionRelationListDocument>

Retrieve a collection relation ¶

GET /collection/relation/(relation-id)¶

Retrieves the relation with the id relation-id.

Status Codes:	404 Not found – Could not find the relation identified by `relation-id`.
Produces:	application/xml, application/json – CollectionRelationDocument.
Role:	_collection_relation_read

Update a collection relation ¶

PUT /collection/relation/(relation-id)¶

Updates the relation metadata for a relation with the id relation-id.

Query Parameters:	direction (string) – `U` - Set the direction of the relation as undirectional. `S` - Set the direction as the first collection of the relation being the source and the second one being the target. `T` - Set the direction as the second collection of the relation being the source and the first one being the target.
Status Codes:	404 Not found – Could not find the relation identified by `relation-id`.
Produces:	application/xml, application/json – The updated collection described as an CollectionRelationDocument.
Role:	_relation_write

Query parameters of the form key=value are used to modify the metadata of the relation.

Delete an collection relation ¶

DELETE /collection/relation/(relation-id)¶

Deletes the relation with the id relation-id.

Status Codes:	200 OK – The collection relation is deleted. 404 Not found – Could not find the relation identified by `relation-id`.
Role:	_collection_relation_write