Item-to-item relations

This section describes relations between items. The relation can be used to find ancestors, derived items, or simply loosely related items.

Type of relations

Relations

  • can be directional or undirectional. In a directional relation, one item is the source and another item is the target. In an undirectional relation, the two items are treated equally
  • are manually built using the API or created automatically. An example of automatically built relations is the timeline conform method, which automatically creates directed relations
  • 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.

Automatically generated relations

Item-to-item relations are automatically generated by timeline conform actions. These relations are directional from source item(s) to target item. The relations have the following tags:

  • key=conform
  • conform-job= { conform-job }

Managing item relations

Get list of item relations

GET /item/(id)/relation

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

Query Parameters:
 
  • direction
    • U - Only return undirectional relations where id is part of.
    • S - Only return directional relations where id is the source item.
    • T - Only return directional relations where id is the target item.
    • D - Only return directional relations where id is the source or target item.
    • A (default) - Return all relations that id is a part of.
Status Codes:
  • 400 – An invalid direction has been specified.
  • 404 – Could not find the item identified by id.
Produces:
  • application/xml, application/jsonItemRelationListDocument.
  • text/plainCR 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).

Generate a new item relation

POST /item/(id1)/relation/(id2)

Generates a new relation between the two items with the given ids, id1 and id2, with the given parameters.

Query Parameters:
 
  • direction

    Mandatory parameter.

    • U - Set the direction of the relation as undirectional.
    • S - Set the direction as id1 being the source and id2 being the target.
    • T - Set the direction as id2 being the source and id1 being the target.
  • allowDuplicate

    Optional parameter.

    New in version 4.8.

    • true or false - True is default. Avoid adding duplicate relations by setting this to false.
Status Codes:
  • 400 Bad request – Both id1 and id2 identifies the same item, or the direction is invalid.
  • 404 Not found – Could not find the item identified by id1 or id2.
Produces:
Role:

_relation_write

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

Retrieve a specific item relation

GET /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:
Role:

_relation_read

Update an item relation

PUT /relation/(relation-id)

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

Query Parameters:
 
  • direction

    Optional parameter.

    • U - Set the direction of the relation as undirectional.
    • S - Set the direction as id1 being the source and id2 being the target.
    • T - Set the direction as id2 being the source and id1 being the target.
Status Codes:
  • 404 Not found – Could not find the relation identified by relation-id.
Produces:
Role:

_relation_write

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

Delete an item relation

DELETE /relation/(relation-id)

Deletes the relation with the id relation-id.

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

_relation_write

Delete all item relations

DELETE /item/(id)/relation

New in version 4.8.

Deletes the relations with the specified direction or all relations.

Query Parameters:
 
  • direction

    Optional parameter.

    • A - This is the default value. Deletes all relations id1 is involved in.
    • U - Deletes only the relations with the direction as undirectional.
    • S - Deletes only the relations where id1 is the source and id2 is the target.
    • T - Deletes only the relations where id2 is the source and id1 is the target.
Status Codes:
  • 200 OK – The item relation is deleted.
Role:

_relation_write

Delete all relations between two items

DELETE /item/(id)/relation/(id2)

New in version 4.8.

Deletes the relations with the specified direction or all relations between id1 and id2.

Query Parameters:
 
  • direction

    Optional parameter.

    • A - This is the default value. Deletes all relations between id1 and id2.
    • U - Deletes only the relations with the direction as undirectional.
    • S - Deletes only the relations where id1 is the source and id2 is the target.
    • T - Deletes only the relations where id2 is the source and id1 is the target.
Status Codes:
  • 200 OK – The item relation is deleted.
Role:

_relation_write