CollectionObject Service RESTful APIs
Brief Description
The purpose of the CollectionObject Service is to manage records of information called CollectionObjects. In CollectionSpace, a "CollectionObject" is a record of information about a collection item -e.g. a single artifact, a box of shards, a specimen, etc. A museum or other repository using CollectionSpace to manage their collections can create and maintain a CollectionObject record for each item in their collection.
REST-based API
The CollectionObject Service offers a REST-based Application Programming Interface (API) to CRUD (create, read, update, and delete) operations on individual CollectionObject instances, plus list operations on multiple CollectionObject instances. These follow the Common model for CollectionSpace REST services.
- CollectionObject Service RESTful APIs#CollectionObject CRUD+L services
- CollectionObject Service RESTful APIs#CollectionObject REST payload schemas
CollectionObject CRUD+L services
Create a CollectionObject
Creates a new CollectionObject record. Assigns a unique, service-specified CollectionSpace ID (CSID) to that CollectionObject record. Follows standard Create model. See the documentation of the CollectionObject schema, below. Example:
POST /cspace-services/collectionobjects HTTP/1.1
Read a CollectionObject
Reads an existing CollectionObject record, specified by its CollectionSpace ID (CSID). Follows standard Read model. See the documentation of the CollectionObject schema, below. Example:
GET /cspace-services/collectionobjects/{id} HTTP/1.1
Update a CollectionObject
Updates an existing CollectionObject record, specified by its CollectionSpace ID (CSID). Follows standard Update model. See the documentation of the CollectionObject schema, below. Example:
PUT /cspace-services/collectionobjects/{id} HTTP/1.1
Delete a CollectionObject
Deletes an existing CollectionObject record, specified by its CollectionSpace ID (CSID). Follows standard Delete model. Example:
DELETE /cspace-services/collectionobjects/{id} HTTP/1.1
List CollectionObject instances
Lists existing CollectionObject records, with summary information for each. Follows standard List model. See the documentation of the CollectionObject list schema, below. Example:
GET /cspace-services/collectionobjects/ HTTP/1.1
List hierarchical related records via showRelations
for structured objects
To list records structurally related to a particular CollectionObject (aka, a structured object) record, specified by its CollectionSpace ID (CSID), add the showRelations=true
query parameter to the request URL.
For example, to list records structurally related to the Cataloging / CollectionObject record specified by CSID 850161ed-466c-4af2-bc45:
GET /cspace-services/collectionobjects/850161ed-466c-4af2-bc45?showRelations=true HTTP/1.1
This request returns, in a relations-common-list
part of the response payload, a list of Relation records. The Cataloging / CollectionObject record specified by CSID 850161ed-466c-4af2-bc45 will be either the subject or object of each of the Relation records in that list. The records to which it is related will be specified, in turn, by both document type and CSID, in the reciprocal fields of each item in the list.
List related records via showAllRelations
To list records related to a particular CollectionObject (aka, cataloging) record, specified by its CollectionSpace ID (CSID), add the showAllRelations=true
query parameter to the request URL.
For example, to list records related to the Cataloging / CollectionObject record specified by CSID 850161ed-466c-4af2-bc45:
GET /cspace-services/collectionobjects/850161ed-466c-4af2-bc45?showAllRelations=true HTTP/1.1
This request returns, in a relations-common-list
part of the response payload, a list of Relation records. The Cataloging / CollectionObject record specified by CSID 850161ed-466c-4af2-bc45 will be either the subject or object of each of the Relation records in that list. The records to which it is related will be specified, in turn, by both document type and CSID, in the reciprocal fields of each item in the list.
CollectionObject REST payload schemas
CollectionObject instance schema
The schemas below are severely abbreviated, and are thus illustrative. For a full list of the fields that may potentially be present in payloads when creating, updating, or reading individual CollectionObject records, please see the CollectionObject record schema for release 0.5.
Create and Update should use the following schema:
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <ns2:collectionobjects-common xmlns:ns2="http://services.collectionspace.org/collectionobject"> <objectNumber>2010.5.18</objectNumber> <objectName>Laguna Tide Pool</objectName> <title>Impressionist Painting</title> ... </ns2:collectionobjects-common>
Read will return the following schema:
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <ns2:collectionobjects_common xmlns:ns2="http://collectionspace.org/services/collectionobject" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://collectionspace.org/services/collectionobject http://services.collectionspace.org/collectionobject/collectionobjects_common.xsd"> <objectNumber>2010.5.18</objectNumber> <objectName>Laguna Tide Pool</objectName> <title>Impressionist Painting</title> ... </ns2:collectionobjects-common>
CollectionObject list schema
List (and variants) will return the following schema. This schema includes the uri and csid fields to help facilitate access to individual records:
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <ns2:collectionobjects-common-list xmlns:ns2="http://collectionspace.org/services/collectionobject"> <collectionobject-list-item> <objectNumber>2010.5.18</objectNumber> <title>Painting of a Tide Pool</title> <uri>/collectionobjects/f0cf4c50-8f8a-4df0-869a</uri> <csid>f0cf4c50-8f8a-4df0-869a</csid> </collectionobject-list-item> .... </ns2:collectionobjects-common-list>