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/json – ItemRelationListDocument.
- 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).
- direction –
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.
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: - application/xml, application/json – ItemRelationDocument
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.
- direction –
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: - application/xml, application/json – ItemRelationDocument.
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: - application/xml, application/json – The updated item described as an ItemRelationDocument.
Role: _relation_write
Query parameters of the form key=value are used to modify the metadata of the relation.
- direction –
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