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 whereid
is part of.S
- Only return directional relations whereid
is the source item.T
- Only return directional relations whereid
is the target item.D
- Only return directional relations whereid
is the source or target item.A
(default) - Return all relations thatid
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
andid2
, with the given parameters.Query Parameters: - direction –
Mandatory parameter.
U
- Set the direction of the relation as undirectional.S
- Set the direction asid1
being the source andid2
being the target.T
- Set the direction asid2
being the source andid1
being the target.
- allowDuplicate –
Optional parameter.
New in version 4.8.
true
orfalse
- True is default. Avoid adding duplicate relations by setting this to false.
Status Codes: - 400 Bad request – Both
id1
andid2
identifies the same item, or the direction is invalid. - 404 Not found – Could not find the item identified by
id1
orid2
.
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
- 404 Not found – Could not find the relation identified by
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 asid1
being the source andid2
being the target.T
- Set the direction asid2
being the source andid1
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
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 relationsid1
is involved in.U
- Deletes only the relations with the direction as undirectional.S
- Deletes only the relations whereid1
is the source andid2
is the target.T
- Deletes only the relations whereid2
is the source andid1
is the target.
Status Codes: - 200 OK – The item relation is deleted.
Role: _relation_write
- direction –
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
andid2
.Query Parameters: - direction –
Optional parameter.
A
- This is the default value. Deletes all relations betweenid1
andid2
.U
- Deletes only the relations with the direction as undirectional.S
- Deletes only the relations whereid1
is the source andid2
is the target.T
- Deletes only the relations whereid2
is the source andid1
is the target.
Status Codes: - 200 OK – The item relation is deleted.
Role: _relation_write
- direction –