Relationship Service RESTful APIs
Brief Description
Assumptions
For a complete list of assumptions, visit the Service Description and Assumptions page.
References
Relationship Requirements
Relationship Stories
Relationship Service Description and Assumptions
Relationship Service Entity Diagrams
REST-based APIs - A Template for Services
REST-based API
The Relationship Service offers a REST-based Application Programming Interface (API) to CRUD (create, read, update, and delete) operations on individual Relationship instances, plus list operations on multiple Relationship instances. These follow the Common model for CollectionSpace REST services.
Relationship CRUD+L services
Create an Relationship
Creates a new Relationship record. Assigns a unique, service-specified CollectionSpace ID (CSID) to that Relationship record. Follows standard Create model. See the documentation of the Relationship schema, below. Example:
POST /cspace-services/relations HTTP/1.1
Read an Relationship
Reads an existing Relationship record, specified by its CollectionSpace ID (CSID). Follows standard Read model. See the documentation of the Relationship schema, below. Example:
GET /cspace-services/relations/{id} HTTP/1.1
Update an Relationship
Updates an existing Relationship record, specified by its CollectionSpace ID (CSID). Follows standard Update model. See the documentation of the Relationship schema, below. Example:
PUT /cspace-services/relations/{id} HTTP/1.1
Delete an Relationship
Deletes an existing Relationship record, specified by its CollectionSpace ID (CSID). Follows standard Delete model. Example:
DELETE /cspace-services/relations/{id} HTTP/1.1
List Relationship instances
Lists existing Relationship records, with summary information for each. Follows standard List model. See the documentation of the Relationship list schema, below.
GET /cspace-services/relations HTTP/1.1
List supports query parameters for customizing list results, such as pagination controls, query filters, and sorting options. For example:
GET /cspace-services/relations?pgSz=10 HTTP/1.1
List also supports query parameters for searching for matching records, including keyword search. For example:
GET /cspace-services/relations?kw=foo&pgSz=10 HTTP/1.1
Finally, List also supports a special set of query parameters, specific to the Relationship service:
sbj = used to specify the subject's CSID
sbjType = used to specify the type of the subject
obj = used to specify the object's CSID
objType = used to specify the type of the object
prd = used to specify the type of the relationship
By default, all set query parameters will be AND'ed to form the final query. For example, the following query will return all relations with the subject type of "collectionobjects" and an object type of "intakes":
GET /cspace-services/relations?sbjType=collectionobjects&objType=intakes
Relationship REST payload schemas
objectName and objectNumber
Each service may define an objectName and an objectNumber property for list results. The list shows a number and name for each item in the list. Different services determine what that maps to in their own schemae. The mechanism for this is in the tenant-bindings.xml file:
<tenant:serviceBindings name="ObjectExit" type="procedure" version="0.1"> <service:properties xmlns:service='http://collectionspace.org/services/common/service'> <types:item><types:key>objectNameProperty</types:key><types:value>currentOwner</types:value></types:item> <types:item><types:key>objectNumberProperty</types:key><types:value>exitNumber</types:value></types:item> </service:properties> ... </tenant:serviceBindings>
Relationship instance schema
For a full list of the fields that may potentially be present in payloads when creating, updating, or reading individual Relationship records, please see the Relationship record schema.
Create and Update should use the following schema:
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <ns2:relations_common xmlns:ns2="http://collectionspace.org/services/relation"> <subjectCsid>e62d2306-518b-414b-9591</documentId1> <subjectDocumentType>collectionobjects</documentType1> <relationshipType>affects</relationshipType> <objectCsid>814ed9d4-3315-44fc-993b</documentId2> <objectDocumentType>collectionobjects</documentType2> </ns2:relations_common>
Read will return the following schema (noting that in this instance, document types were not supplied during the relevant Create operation):
<?xml version="1.0" encoding="UTF-8"?> <ns2:relations_common xsi:schemaLocation="http://collectionspace.org/services/relation http://services.collectionspace.org/relation/relations_common.xsd"> <subjectCsid>a780de76-d837-4e9b-ad5e</documentId1> <subjectDocumentType>collectionobjects</documentType1> <relationshipType>affects</relationshipType> <objectCsid>6c825332-8abf-4285-9a45</documentId2> <objectDocumentType>intakes</documentType2> </ns2:relations_common>
Relationship list schema
List (and variants) will return the following schema. This schema includes the uri and csid to help facilitate access to individual records.
Currently, two fields in the list schema are currently named differently than their corresponding fields in the individual record schema: subjectCsid in the list schema corresponds to documentId1 in the individual record schema, while objectCsid in the list schema corresponds to documentId2 in the individual record schema.
As of version 1.7, the Relations service returns a nested structure for subject and object. There are new fields in the subject and object elements:
uri | The uri which points to subject item, |
csid | The csid of the subject item |
service | The name of the service that contains the subject |
number | The objectNumber property, as defined in tenant-bindings.xml |
name | The objectName property, as defined in tenant-bindings.xml |
documentType | Maps from subjectDocumentType or objectDocumentType from CREATE or UPDATE |
documentTypeFromModel | Maps to the Nuxeo documentType for the related item |
error | This optional element will only be present if this relation points to a missing related item |
order | Optional. For use by app/gui |
key | Informational. For use by services to tag which predicate led to inclusion, etc. |
<relation-list-item> <uri>/relations/8f67bbb3-d250-41e9-9151</uri> <csid>8f67bbb3-d250-41e9-9151</csid> <subjectCsid>7c5f5e57-212f-4c7e-9792</subjectCsid> <relationshipType>affects</relationshipType> <predicate>affects</predicate> <objectCsid>62c60d67-5249-4ae7-ac68</objectCsid> <subject> <uri></uri> <csid>7c5f5e57-212f-4c7e-9792</csid> <service>acquisitions</service> <number>123456</number> <name></name> <documentType>acquisitions</documentType> <documentTypeFromModel>Acquisition</documentTypeFromModel> </subject> <object> <uri></uri> <csid>62c60d67-5249-4ae7-ac68</csid> <service>objectexit</service> <name></name> <number>56789</number> <documentType>objectexit</documentType> <documentTypeFromModel>ObjectExit</documentTypeFromModel> </object> </relation-list-item>
Here's a full result list with two relations.
<ns3:relations-common-list> <pageNum>0</pageNum> <pageSize>40</pageSize> <itemsInPage>2</itemsInPage> <totalItems>2</totalItems> <fieldsReturned>subjectCsid|relationshipType|predicateDisplayName|objectCsid|uri|csid|subject|object</fieldsReturned> <relation-list-item> <uri>/relations/2dd20c31-87b2-4b16-8484</uri> <csid>2dd20c31-87b2-4b16-8484</csid> <subjectCsid>f9d38ebd-e0c4-49a1-a2a6</subjectCsid> <relationshipType>affects</relationshipType> <predicate>affects</predicate> <objectCsid>19661dd6-13fa-4c3e-aed5</objectCsid> <subject> <uri></uri> <csid>f9d38ebd-e0c4-49a1-a2a6</csid> <service>collectionobjects</service> <number>32</number> <documentType>collectionobjects</documentType> <documentTypeFromModel>CollectionObject</documentTypeFromModel> </subject> <object> <uri></uri> <csid>19661dd6-13fa-4c3e-aed5</csid> <service>collectionobjects</service> <number>generic0 - objectNumber</number> <documentType>collectionobjects</documentType> <documentTypeFromModel>CollectionObject</documentTypeFromModel> </object> </relation-list-item> <relation-list-item> <uri>/relations/30287a21-eac4-4c44-ac09</uri> <csid>30287a21-eac4-4c44-ac09</csid> <subjectCsid>19661dd6-13fa-4c3e-aed5</subjectCsid> <relationshipType>affects</relationshipType> <predicate>affects</predicate> <objectCsid>f9d38ebd-e0c4-49a1-a2a6</objectCsid> <subject> <uri></uri> <csid>19661dd6-13fa-4c3e-aed5</csid> <service>collectionobjects</service> <number>generic0 - objectNumber</number> <documentType>collectionobjects</documentType> <documentTypeFromModel>CollectionObject</documentTypeFromModel> </subject> <object> <uri></uri> <csid>f9d38ebd-e0c4-49a1-a2a6</csid> <service>collectionobjects</service> <number>32</number> <documentType>collectionobjects</documentType> <documentTypeFromModel>CollectionObject</documentTypeFromModel> </object> </relation-list-item> </ns3:relations-common-list>