...
- Multiple Cataloging / CollectionObject records can be related in a hierarchy. Each record can optionally be related to one Broader Object (its immediate parent) and/or one or more Object Components (its immediate children).
Multiple authority term records can be related in a hierarchy. Each term can optionally be related to one Broader Context term (its immediate parent) and/or one or more Narrower Context terms (its immediate children).
A sample three-level authority term hierarchy:Broader Context
Term
Narrower Context
-
North America
Canada
North America
Canada
Ontario
QuebecCanada
Ontario
-
Canada
Quebec
-
There are three different categories of REST API calls to return related records. The calls in two of these categories each return lists of Relation records, the "linking" records that relate any two other types of records. Calls in the third category, in contrast, directly return lists of records of a particular type that are related to the specified record.
...
The following errors may be returned in response to Create requests. Your code should check for each of these, while noting that not every CollectionSpace service may currently return all of the errors below:
Error (Status Code) | Meaning | Returned When |
|---|---|---|
400 | Bad Request | The resource could not be created because the data sent in the entity body of the request was bad, as determined by the service. |
401 | Unauthorized | The resource could not be created because the client submitting the request either has not provided authentication credentials, or authentication failed (e.g. due to an invalid username or password) after such credentials were provided. |
403 | Forbidden | The resource could not be created because the client submitting the request was not authorized to create new resources in this container. |
409 | Conflict | The resource could not be created because the submitted data would create a duplicate (non-unique) resource, as determined by the service. |
500 | Internal Server Error | A service error prevented the resource from being created. |
Read an object/procedure/record instance
...
The following errors may be returned in response to Read requests. Your code should check for each of these, while noting that not every CollectionSpace service may currently return all of the errors below:
Error (Status Code) | Meaning | Returned When |
|---|---|---|
401 | Unauthorized | The resource could not be read (i.e. returned) because the client submitting the request either has not provided authentication credentials, or authentication failed (e.g. due to an invalid username or password) after such credentials were provided. |
403 | Forbidden | The resource could not be read because the client submitting the request was not authorized to read it. |
404 | Not Found | The resource requested for reading does not exist. (When the |
500 | Internal Server Error | A service error prevented the resource from being read. |
Update an object/procedure/record instance
...
The following errors may be returned in response to Update requests. Your code should check for each of these, while noting that not every CollectionSpace service may currently return all of the errors below:
Error (Status Code) | Meaning | Returned When |
|---|---|---|
400 | Bad Request | The resource could not be updated because the data sent in the entity body of the request was bad, as determined by the service. |
401 | Unauthorized | The resource could not be updated because the client submitting the request either has not provided authentication credentials, or authentication failed (e.g. due to an invalid username or password) after such credentials were provided. |
403 | Forbidden | The resource could not be updated because the client submitting the request was not authorized to update resources in this container. |
404 | Not Found | The resource requested for updating does not exist. |
500 | Internal Server Error | A service error prevented the resource from being updated. |
Delete an object/procedure/record instance
...
The following errors may be returned in response to Delete requests. Your code should check for each of these, while noting that not every CollectionSpace service may currently return all of the errors below:
Error (Status Code) | Meaning | Returned When |
|---|---|---|
401 | Unauthorized | The resource could not be deleted because the client submitting the request either has not provided authentication credentials, or authentication failed (e.g. due to an invalid username or password) after such credentials were provided. |
403 | Forbidden | The resource could not be deleted because the client submitting the request was not authorized to delete it. |
404 | Not Found | The resource requested for deletion does not exist. |
500 | Internal Server Error | A service error prevented the resource from being deleted. |
List All object/procedure/record instances
...
If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error.
Error (Status Code) | Meaning | Returned When |
|---|---|---|
401 | Unauthorized | The list of resources could not be read (i.e. returned) because the client submitting the request either has not provided authentication credentials, or authentication failed (e.g. due to an invalid username or password) after such credentials were provided. |
403 | Forbidden | The list of resources could not be read because the client submitting the request was not authorized to read it. |
404 | Not Found | The list of resources requested for reading does not exist. This may occur, for example, if a path element in the request URL is incorrect. Note that if a list of resources does exist, but currently contains zero items, a success response with a "200 OK" HTTP status code will be returned, containing an empty list - a list with only a root element, but no child elements. |
500 | Internal Server Error | A service error prevented the list of resources from being read. |
Keyword Search for object/procedure/record instances
...
If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error.
Error (Status Code) | Meaning | Returned When |
|---|---|---|
401 | Unauthorized | The list of resources could not be read (i.e. returned) because the client submitting the request either has not provided authentication credentials, or authentication failed (e.g. due to an invalid username or password) after such credentials were provided. |
403 | Forbidden | The list of resources could not be read because the client submitting the request was not authorized to read it. |
404 | Not Found | The list of resources does not exist. This may occur, for example, if a path element in the request URL is incorrect. Note that if a list of resources does exist, but currently contains zero items that are matched by the partial term, a success response with a "200 OK" HTTP status code will be returned, containing an empty list - a list with only a root element, but no child elements. |
500 | Internal Server Error | A service error prevented the list of resources from being read. |
Term Status Filtering for Authority terms
...
If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error.If all terms match on (e.g. are filtered out by) the termStatus values provided in the filter, a response with a "200 OK" HTTP status code, containing an empty list - a list with only a root element, but no child elements - is returned.
Error (Status Code) | Meaning | Returned When |
|---|---|---|
401 | Unauthorized | The list of resources could not be read (i.e. returned) because the client submitting the request either has not provided authentication credentials, or authentication failed (e.g. due to an invalid username or password) after such credentials were provided. |
403 | Forbidden | The list of resources could not be read because the client submitting the request was not authorized to read it. |
404 | Not Found | The list of resources does not exist. This may occur, for example, if a path element in the request URL is incorrect. Note that if a list of resources does exist, but currently contains zero items that are matched by the partial term, a success response with a "200 OK" HTTP status code will be returned, containing an empty list - a list with only a root element, but no child elements. |
500 | Internal Server Error | A service error prevented the list of resources from being read. |
Related Authority References for object/procedure/record instances
...
If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error.
Error (Status Code) | Meaning | Returned When |
|---|---|---|
401 | Unauthorized | The list of authority references could not be read (i.e. returned) because the client submitting the request either has not provided authentication credentials, or authentication failed (e.g. due to an invalid username or password) after such credentials were provided. |
403 | Forbidden | The list of authority references could not be read because the client submitting the request was not authorized to read the relevant resource. |
404 | Not Found | The resource from which a list of authority references was requested does not exist. Note that if the resource does exist, but currently contains no authority references, a success response with a "200 OK" HTTP status code will be returned, containing an empty list - a list with only a root element, but no child elements. |
500 | Internal Server Error | A service error prevented the list of authority references, or the relevant resource from which that list was requested, from being read. |
Related Object References for authority
...
items
Retrieves and returns all objects (procedures, etc) that reference a given authority item. Information returned includes an abstraction of the fields in which they are used.
...
| Code Block |
|---|
HTTP/1.1 200 OK
...
Content-Type: application/xml
Content-Length: nnn
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:authority-ref-doc-list xmlns:ns2="http://collectionspace.org/services/common/authorityref">
<authority-ref-doc-item>
<docType>Intake</docType>
<docId>d38d5652-5e51-4a15-9ab9</docId>
<docNumber>IN2011.1</docNumber>
<sourceField>intakes_common:depositor</sourceField>
<value>urn:cspace:core.collectionspace.org:personauthorities:name(person):item:name(JaneDoe1705026588599)'Jane Doe'</value>
<uri>/intakes/d38d5652-5e51-4a15-9ab9</uri>
</authority-ref-doc-item>
...
</ns2:authority-ref-doc-list> |
In the above example, the 'depositor' field of the specified Intake resource has been identified as containing the term item of interest (from a specified Person Authority). Since any type of object or procedure could be returned, the listed information fields are abstract. The document ID is the internal CSID. The docNumber is drawn from a field configured in the tenant bindings to be a "number" field. A "name" field can also be configured. The source field in the referring object record is indicated, as well as the urivalue of that field. The value can be used to determine the exact term on that was used on the record, in the case that the given authority item contains multiple terms (synonyms).
If an object a record has multiple references to a given termauthority item, multiple entries for that referring object record will be returned.
An additional query/filter parameter may be specified: "type". This specifies one of a set of configured "classes" of document types to return. In the default configuration, there are types defined "object", "procedure", "authority", etc. If no type is specified, it will default to "procedure."
...
If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error.
Error (Status Code) | Meaning | Returned When |
|---|---|---|
401 | Unauthorized | The list of |
references could not be read (i.e. returned) because the client submitting the request either has not provided authentication credentials, or authentication failed (e.g. due to an invalid username or password) after such credentials were provided. | ||
403 | Forbidden | The list of |
references could not be read because the client submitting the request was not authorized to read the relevant resource. | ||
404 | Not Found | The resource from which a list of |
references was requested does not exist. Note that if the resource does exist, but currently contains no |
references to the item, a success response with a "200 OK" HTTP status code will be returned, containing an empty list - a list with only a root element, but no child elements. | ||
500 | Internal Server Error | A service error prevented the list of |
references, or the relevant resource from which that list was requested, from being read. |
Read workflow state of an object/procedure/record instance
...
If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error.
Error (Status Code) | Meaning | Returned When |
|---|---|---|
400 | Bad Request | The workflow state could not be updated because the data sent in the entity body of the request was bad, as determined by the service. |
401 | Unauthorized | The workflow state could not be read (i.e. returned) because the client submitting the request either has not provided authentication credentials, or authentication failed (e.g. due to an invalid username or password) after such credentials were provided. |
403 | Forbidden | The workflow state could not be read because the client submitting the request was not authorized to read the relevant resource. |
404 | Not Found | The resource from which the workflow state was requested does not exist. |
500 | Internal Server Error | A service error prevented the workflow state from being read. |
Update workflow state of an object/procedure/record instance
...
If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error.
Error (Status Code) | Meaning | Returned When |
|---|---|---|
401 | Unauthorized | The workflow state could not be updated because the client submitting the request either has not provided authentication credentials, or authentication failed (e.g. due to an invalid username or password) after such credentials were provided. |
403 | Forbidden | The workflow state could not be updated because the client submitting the request was not authorized to update that state. |
404 | Not Found | The resource on which a workflow state update was requested does not exist. |
500 | Internal Server Error | A service error prevented the workflow state from being updated. |
Versions 2.2 and earlier
In versions 2.2 and earlier, the only meaningful workflow states to which you can update (or "transition") a record in CollectionSpace are:
...
If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error.
Error (Status Code) | Meaning | Returned When |
|---|---|---|
400 | Bad Request | The workflow state could not be updated because the data sent in the entity body of the request was bad, as determined by the service. |
401 | Unauthorized | The workflow state could not be updated because the client submitting the request either has not provided authentication credentials, or authentication failed (e.g. due to an invalid username or password) after such credentials were provided. |
403 | Forbidden | The workflow state could not be updated because the client submitting the request was not authorized to update that state. |
404 | Not Found | The resource on which a workflow state update was requested does not exist. |
500 | Internal Server Error | A service error prevented the workflow state from being updated. |
List related records
| Note |
|---|
This section is an early placeholder; it needs considerable expansion and refinement. |
...