Brief Description

Error rendering macro 'excerpt-include' : No link could be created for 'collectionspace:Relationship Service Description and Assumptions'.

For a full description, visit the Service Description and Assumptions page.

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
Relationship REST payload schemas

Relationship CRUD+L services

Create an Relationship

Creates a new Relationship record. Assigns a unique, service-specified /wiki/spaces/collectionspace/pages/666274321 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 /wiki/spaces/collectionspace/pages/666274321. 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 /wiki/spaces/collectionspace/pages/666274321. 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 /wiki/spaces/collectionspace/pages/666274321. 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 "Collectionobject" and an object type of "Intake":

GET /cspace-services/relations?sbjType=Collectionobject&objType=Intake

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, so the path contains the uri for the authority
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>

Service Description Repository

Relationship Service RESTful APIs