Relationship Service Contract Description

Relationship Service Home

Brief Description

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 Service Description and Assumptions
Relationship Service Entity Diagrams
REST-based APIs - A Template for Services

RESTful Interfaces - CRUD Operations

The Relation Service offers a REST-based Application Programming Interface (API) to CRUD (create, read, update, and delete) operations on individual Relation records.

In this API, there is also an operation to retrieve a list with summary information about all relation records. The IDs returned in that list can be used in the aforementioned CRUD operations.

• List All Relation records
• Create a Relation
• Read a Relation
• Update a Relation
• Delete a Relation

List All Relation records

Description

Gets summary information about all relation records. This includes the CollectionSpace ID (cid) of each object, which can be included in the URIs of subsequent requests in order to read, update, or delete specific objects.

Authentication

In Release 0.1, no authentication credentials are requested by the service.

The service currently performs its own internal authentication, using HTTP Basic authentication, to Nuxeo's REST-based API. This will change in subsequent service releases.

Arguments

This service call currently does not accept query parameters or other arguments.

Example: Request

Send this HTTP request:

GET /helloworld/cspace-nuxeo/relations/ HTTP/1.1

To do this via a web browser:

http://demo.collectionspace.org:8080/helloworld/cspace-nuxeo/relations/

To do this via the 'curl' command-line utility:

curl http://demo.collectionspace.org:8080/helloworld/cspace-nuxeo/relations/

Example: Success response

On success, a response with a "200 OK" HTTP status code, followed by a list containing summary information for each of the existing relation records, if any, is returned:

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: nnnn
...

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:collection-object-list xmlns:ns2="http://collectionspace.org/hello">
  <collection-object-list-item>
    <objectNumber>CollectionSpace-Relation</objectNumber>
    <uri>/default/59242af0-0463-4fb2-af0d-2467186c2848</uri>
    <csid>59242af0-0463-4fb2-af0d-2467186c2848</csid>
  </collection-object-list-item>
  <collection-object-list-item>
    <objectNumber>CollectionSpace-Relation</objectNumber>
    <uri>/default/7e09e20a-8bf0-4a30-89ea-1baf7ffd0b04</uri>
    <csid>7e09e20a-8bf0-4a30-89ea-1baf7ffd0b04</csid>
  </collection-object-list-item>
  ...
</ns2:collection-object-list>

If no relation records are found, a response with a "200 OK" HTTP status code, followed by an empty list, is returned:

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: nnnn
...

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:collection-object-list xmlns:ns2="http://collectionspace.org/hello"/>

Error Codes

To determine if an error occurred, check the HTTP Status Code that is returned in the response's HTTP headers. Any non 2xx status code represents an error condition.

Nearly every HTTP client library or framework will offer a call that allows you to easily examine the status code of the response. In 'curl', you can dump to a file the HTTP headers that you receive in a response, by adding the '-D {filename}' parameter to your request.

Create a Relation

Description

Creates a new relation record. Assigns a unique, service-specified CollectionSpace ID (csid) to that object.

Authentication

In Release 0.1, no authentication credentials are requested by the service.

The service currently performs its own internal authentication, using HTTP Basic authentication, to Nuxeo's REST-based API. This will change in subsequent service releases.

Arguments

This service call currently does not accept query parameters or other arguments.

Example: Request

Send this HTTP request:

POST /helloworld/cspace-nuxeo/relations HTTP/1.1
Content-Type: application/xml

with an entity body containing a valid XML representation of a Relation; e.g.:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:collection-object xmlns:ns2="http://collectionspace.org/hello">
  <objectNumber>2</objectNumber>
  <otherNumber>3</otherNumber>
  <briefDescription>description</briefDescription>
  <comments></comments>
  <distFeatures></distFeatures>
  <objectName>Left-handed screwdriver</objectName>
  <responsibleDept></responsibleDept>
  <title></title>
</ns2:collection-object>

To do this via the 'curl' command-line utility:

curl -X POST -H "Content-Type: application/xml" \
http://demo.collectionspace.org:8080/helloworld/cspace-nuxeo/relations/ -T - < {data}

(The "-T -" parameter above specifies that the body of the request will come from standard input.)

Or, alternately:

curl -X POST -H "Content-Type: application/xml" \
http://demo.collectionspace.org:8080/helloworld/cspace-nuxeo/relations -T {filename or path to file containing data}

(Note that in this alternate request using 'curl', there should not be a closing slash at the end of the name of the container to which the new relation record is to be added; e.g. end your URL with "relations', not "relations/". That is because at least some versions of curl appear to append the name of the file being uploaded to the URL, following a closing slash.)

Where {data} or {filename or path to file containing data} is a valid XML representation of a Relation, provided via standard input or stored in a text file, respectively.

In both instances, the "-H "Content-Type: application/xml" is required; this adds a "Content-Type: application/xml" header line to the request headers.

Example: Success response

On success, a response with a "201 Created" HTTP status code is returned:

HTTP/1.1 201 Created
Content-Type: application/xml
Content-Length: nnnn
...

Error Codes

To determine if an error occurred, check the HTTP Status Code that is returned in the response's HTTP headers. Any non 2xx status code represents an error condition.

Nearly every HTTP client library or framework will offer a call that allows you to easily examine the status code of the response. In 'curl', you can dump to a file the HTTP headers that you receive in a response, by adding the '-D {filename}' parameter to your request.

Read a Relation

Description

Gets (reads) information about a single relation record, specified by its CollectionSpace ID (csid).

Authentication

In Release 0.1, no authentication credentials are requested by the service.

The service currently performs its own internal authentication, using HTTP Basic authentication, to Nuxeo's REST-based API. This will change in subsequent service releases.

Arguments

This service call currently does not accept query parameters or other arguments.

Example: Request

Send this HTTP request:

GET /helloworld/cspace-nuxeo/relations/{id} HTTP/1.1

To do this via a web browser:

http://demo.collectionspace.org:8080/helloworld/cspace-nuxeo/relations/{id}

To do this via the 'curl' command-line utility:

curl http://demo.collectionspace.org:8080/helloworld/cspace-nuxeo/relations/{id}

Where {id} is a CollectionSpace ID (csid), such as 59242af0-0463-4fb2-af0d-2467186c28480. To identify the ID of a specific document, List All Relation records or check the response from a request to Create a Relation.

Example: Success response

On success, a response with a "200 OK" HTTP status code and a representation of the requested relation record is returned:

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: nnnn
...

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:collection-object xmlns:ns2="http://collectionspace.org/hello">
  <objectNumber>
  objectNumber-1239399498565
  </objectNumber>
  <otherNumber>
  </otherNumber>
  <briefDescription>
  </briefDescription>
  <comments>
  </comments>
  <distFeatures>
  </distFeatures>
  <objectName>
  objectName-1239399498565
  </objectName>
  <responsibleDept>
  </responsibleDept>
  <title>
  </title>
</ns2:collection-object>

Error Codes

To determine if an error occurred, check the HTTP Status Code that is returned in the response's HTTP headers. Any non 2xx status code represents an error condition.

Nearly every HTTP client library or framework will offer a call that allows you to easily examine the status code of the response. In 'curl', you can dump to a file the HTTP headers that you receive in a response, by adding the '-D {filename}' parameter to your request.

Update a Relation

Description

Updates an individual relation record, specified by its CollectionSpace ID (csid). Accepts a updated relation record in the body of the request. Replaces the values of the existing relation record's fields (elements) with any non-empty values provided in the updated relation record. Empty fields in the updated relation record are ignored.

Subsequent releases may provide more intelligent merging during updates, and/or more client control over how merges are performed.

Authentication

In Release 0.1, no authentication credentials are requested by the service.

The service currently performs its own internal authentication, using HTTP Basic authentication, to Nuxeo's REST-based API. This will change in subsequent service releases.

Arguments

This service call currently does not accept query parameters or other arguments.

Example: Request

Send this HTTP request:

PUT /helloworld/cspace-nuxeo/relations/{id} HTTP/1.1
Content-Type:application/xml

with an entity body containing a valid XML representation of a Relation; e.g.:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:collection-object xmlns:ns2="http://collectionspace.org/hello">
  <objectNumber>2</objectNumber>
  <otherNumber>3</otherNumber>
  <briefDescription>description</briefDescription>
  <comments></comments>
  <distFeatures></distFeatures>
  <objectName>Left-handed screwdriver</objectName>
  <responsibleDept></responsibleDept>
  <title></title>
</ns2:collection-object>

To do this via the 'curl' command-line utility:

curl -X PUT -H "Content-Type: application/xml" \
http://demo.collectionspace.org:8080/helloworld/cspace-nuxeo/relations/{id} -T - < {data}

(The "-T -" parameter above specifies that the body of the request will come from standard input.)

Or, alternately:

curl -X PUT -H "Content-Type: application/xml" \
http://demo.collectionspace.org:8080/helloworld/cspace-nuxeo/relations/{id} \
-T {filename or path to file containing data}

Where {id} is a CollectionSpace ID (csid), such as 59242af0-0463-4fb2-af0d-2467186c28480. To identify the ID of a specific document, List All Relation records or check the response from a request to Create a Relation.

Where {data} or {filename or path to file containing data} is a valid XML representation of a Relation, provided via standard input or stored in a text file, respectively.

In both instances, the "-H "Content-Type: application/xml" is required; this adds a "Content-Type: application/xml" header line to the request headers.

Example: Success response

On success, a response with a "200 OK" HTTP status code and a representation of the updated relation record is returned:

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: nnnn
...

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:collection-object xmlns:ns2="http://collectionspace.org/hello">
  <objectNumber>2</objectNumber>
  <otherNumber>3</otherNumber>
  <briefDescription>description</briefDescription>
  <comments></comments>
  <distFeatures></distFeatures>
  <objectName>Left-handed screwdriver</objectName>
  <responsibleDept></responsibleDept>
  <title></title>
</ns2:collection-object>

Error Codes

To determine if an error occurred, check the HTTP Status Code that is returned in the response's HTTP headers. Any non 2xx status code represents an error condition.

Nearly every HTTP client library or framework will offer a call that allows you to easily examine the status code of the response. In 'curl', you can dump to a file the HTTP headers that you receive in a response, by adding the '-D {filename}' parameter to your request.

Delete a Relation

Description

Deletes a single relation record, specified by its CollectionSpace ID (csid).

Authentication

In Release 0.1, no authentication credentials are requested by the service.

The service currently performs its own internal authentication, using HTTP Basic authentication, to Nuxeo's REST-based API. This will change in subsequent service releases.

Arguments

This service call currently does not accept query parameters or other arguments.

Example: Request

Send this HTTP request:

DELETE /helloworld/cspace-nuxeo/relations/{id} HTTP/1.1

To do this via the 'curl' command-line utility:

curl -X DELETE http://demo.collectionspace.org:8080/helloworld/cspace-nuxeo/relations/{id}

Where {id} is a CollectionSpace ID (csid), such as 59242af0-0463-4fb2-af0d-2467186c28480. To identify the ID of a specific document, List All Relation records or check the response from a request to Create a Relation.

Example: Success response

On success, a response with a "200 OK" HTTP status code is returned:

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: nnnn
...

Error Codes

To determine if an error occurred, check the HTTP Status Code that is returned in the response's HTTP headers. Any non 2xx status code represents an error condition.

Nearly every HTTP client library or framework will offer a call that allows you to easily examine the status code of the response. In 'curl', you can dump to a file the HTTP headers that you receive in a response, by adding the '-D {filename}' parameter to your request.