REST-based API

All of CollectionSpace's exposed services offer a REST-based Application Programming Interface (API). This API allows you to perform CRUD+L operations (create, read, update, and delete of individual items, plus list operations such as list all, query, search and term suggestion) on a variety of entities that represent a museum's or related institution's collections, such as collection objects, acquisitions, and loans. You can also use this same API to manage a number of the internal entities within a CollectionSpace system, such as user accounts.

There are some minor variations in this API from service to service. However, nearly all services accept requests and provide responses in nearly exactly the same way. The API functionality that is common across all the services is documented here. For details of the REST APIs for individual services, please see Service Layer - Services Currently Available.

The general principles of this API are described first, followed by the common features of the CRUD+L operations.

General principles

Item-level CRUD and List operations

Most services support both item-level CRUD operations and List operations (hence "CRUD+L"):

• The item-level CRUD operations allow you to create, read, update and delete individual resources. Most services use a common schema to describe these resources, which is used in both create and update requests, and in the responses returned from read requests. This schema is divided into several sections, following the principles articulated in our Services Architecture.
• The list operations return lists of multiple resources. The list operations of most services use a second, common schema, which returns minimal, summary information about each item, together with identifiers that can be used to individually retrieve more detailed information about any item. The type of data returned for each item is generally independent of the type of list function (e.g. list all, query, term suggestion) for a given service. There are plans to support mechanisms to request additional fields to be added to the returned results, but this functionality is not yet supported. Some (soon, most) services support pagination of list results. See details below, and in individual service API documentation.

Invoking the REST APIs

All services are invoked with HTTP requests:

• HTTP POST requests are used to create items.
• HTTP GET requests are used to read items. They are also used in list operations that may return multiple items, such as list all, query, search and term suggestion.
• HTTP PUT requests are used to update (change) items.
• HTTP DELETE requests are used to delete items.

The specific calls are described in Standard CRUD+L APIs for CollectionSpace services, below.

Payloads

Payloads - data that you will send in some of your requests to the services, and that you will receive in some of your responses from the services - share some common characteristics:

• In the case of all services supporting extensible schema, payloads are MIME multipart messages, with a Content-Type header of multipart/mixed.
• They will consist of one or more parts, separated by part boundaries:
  • Each part is associated with one of the layered schemas, as described in the Schema Extension documentation. Its label indicates its associated schema layer (core, common, domain, or local).
  • Each part will usually contain an XML document. If so, it will have a part-specific content-type application/xml.
  • Each field in an object or procedural record is usually represented by a corresponding element in that XML document.
• In cases where the service does not support an extensible schema or the request or response contains the payload only from a single schema, the Content-type header of application/xml is used. Examples are account service, authorization service, id service, basic list operations, etc.

Sparse payloads

The services support "sparse" payloads, which contain only a subset of the fields listed in the schema for a record type.

When creating or updating a record, any fields not passed in the payload will not be affected:

• On create, missing/unspecified values will take default values - usually null.
• On update, missing/unspecified values will not be changed (except subject to validation rules).

When reading an record, only fields that have non-null values - populated by a prior create or update, or by a service itself - will be returned. Fields containing null values will not be returned.

Repeatable fields and field groups

The services support repeatable (also known variously as repeating, multivalue or multivalued) fields and field groups.

In some service schemas:

• Certain fields can optionally be repeated (that is, occur more than once).
• Certain groups of fields can optionally be repeated.
• Within group of fields that can be repeated, certain fields in that group can optionally be repeated.

As of CollectionSpace Release 0.5, only the first of these three repeatability mechanisms is supported, and only for selected fields.

A repeatable field is represented in payloads in the form of a parent field, which acts solely as a container, and zero or more instances of a repeatable child field. Example:

Authentication

Authentication is required to call CollectionSpace REST services. CollectionSpace REST services use HTTP Basic Authentication with HTTPS server side authentication. An authentication token for the end user must be provided in the HTTP header.

The HTTP error code 401 (Unauthorized) with response message is used by the CollectionSpace services to challenge the authorization of a user agent. Upon receipt of an unauthorized request for a URI within the CollectionSpace protection space, the server will respond with a challenge like the following:

In response, the user agent could send user id and password Base64 encoded as follows:

Where QWxhZGRpbjpvcGVuIHNlc2FtZQ== represent userid:password in Base64 encoded form. Refer to HTTP Basic Authentication for more details.

In an upcoming release of the CollectionSpace system, the calling application must also provide an authorized application ID.

List results, pagination controls and query filters

All (or most) REST services that provide lists of results support pagination of the results. This is controlled with additional parameters to the GET:

• pgSz indicates the number of results to return per page. This defaults to 40 (need to be able to configure this centrally and/or per service), and has a maximum value of 1000 (should probably support configuration of this as well).
• pgNum indicates the (0-based) page number to return. This leverages the pgSz to produce the startign offset for the returned results.

The list schemas for these services include information about the pagination before the list items:

• The <pageNum> element reflects the pgNum request made (0, by default)
• The <pageSize> element reflects the pgSz request made, or the default page size.
• The <totalItems> element reflects the total number of items found for the list or search query.

Some services support query methods to return specific items, e.g., partial matches against a name, or matches against a keyword index. These return results as for the basic list operation, but filtered according to the query parameters. The query parameters are specific to each service, although certain patterns will be seen:

• For those services that support keyword-index search... (this is currently modeled as a "search" sub-resource, which does not follow the model we are describing).
• For those services that support term-completion search, the query parameter "pt=term" specifies the partial term to match.

Standard CRUD+L APIs for CollectionSpace services

Except as noted in individual service REST API documentation, the CollectionSpace services support the following calls.

• Create an object/procedure/record instance
• Read an object/procedure/record instance
• Update an object/procedure/record instance
• Delete an object/procedure/record instance
• List All object/procedure/record instances

Also, except as noted in individual service API documentation, the CollectionSpace service supports schema extension. Therefore, it would use Content-Type: multipart/mixed for Create, Read and Update operations.

Create an object/procedure/record instance

Creates a new object/procedure/record instance. Assigns a unique, service-specified CollectionSpace ID (CSID) to that record. Standard authentication applies, and user must have create privileges for the associated object/procedure/record type.

Calling method and Arguments

Create is invoked as an HTTP POST method on the primary service resource, with a content-type of application/xml. Send an HTTP request of the form (the specific path and schema payload is only an example - the appropriate path and schema is documented in each service API):

Create service calls do not generally accept query parameters or other arguments.

The entity body of your Create request must contain a valid XML representation of the associated object/procedure/record that you wish to create. This may be a sparse payload, containing only selected fields. Each service has a different schema; for details, please see the individual service's documentation.

Responses

On success, a response with a "201 Created" HTTP status code is returned. Note that the Location: header will contain the service path, including the CollectionSpace ID (CSID), to the newly created resource, as in this example:

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.

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:

Read an object/procedure/record instance

Gets (reads) information about a single object/procedure/record instance, specified by its CollectionSpace ID (CSID) as returned by Create, or a List method. Standard authentication applies, and user must have read privileges for the associated object/procedure/record type. 

Calling method and Arguments

Read is invoked as an HTTP GET method on an instance resource (the primary service resource qualified with a CSID value). Send an HTTP request of the form (the specific path is only an example - the appropriate path is documented in each service API):

Read service calls do not generally accept query parameters or other arguments.

Responses

On success, a response with a "200 OK" HTTP status code and a representation of the requested object/procedure/record record is returned, with the associated schema sections represented, as below. See the individual service documentation for schema details.

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.

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:

Update an object/procedure/record instance

Updates an individual object/procedure/record instance, specified by its CollectionSpace ID (CSID) as returned by Create, or a List method. Standard authentication applies, and user must have update privileges for the associated object/procedure/record type.

Calling method and Arguments

Update is invoked as an HTTP PUT method on an instance resource (the primary service resource qualified with a CSID value), with a content-type of application/xml. Send an HTTP request of the form (the specific path and schema payload is only an example - the appropriate path and schema is documented in each service API):

Update service calls do not generally accept query parameters or other arguments.

The entity body of your Update request must contain a valid XML representation of the associated object/procedure/record that you wish to create. This may be a sparse payload, containing only selected fields. Each service has a different schema; for details, please see the individual service's documentation.

Responses

On success, a response with a "200 OK" HTTP status code and a representation of the updated object/procedure/record instance is returned. The body of the response is as for the standard read operation; see Read 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.

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:

Delete an object/procedure/record instance

Deletes an individual object/procedure/record instance, specified by its CollectionSpace ID (CSID) as returned by Create, or a List method. Standard authentication applies, and user must have delete privileges for the associated object/procedure/record type

Calling method and Arguments

Delete is invoked as an HTTP DELETE method on an instance resource (the primary service resource qualified with a CSID value). Send an HTTP request of the form (the specific path is only an example - the appropriate path is documented in each service API):

Delete service calls do not generally accept query parameters or other arguments.

On success, a response with a "200 OK" HTTP status code is returned, with an empty entity body:

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.

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:

List All object/procedure/record instances

Gets summary information about all instances for the associated resource. Instances for which the authenticated user does not have read privileges, will not be returned in results.

Summary information generally includes the CollectionSpace ID (CSID) of each instance, which can be included in the URIs of subsequent requests in order to read, update, or delete specific instances. The specific information returned within the items of a list is documented with each service resource, and may include displayName or refName information for each item.

Calling method and Arguments

List is invoked as an HTTP GET method on the primary resource. Send an HTTP request of the form (the specific path is only an example - the appropriate path is documented in each service API):

As described in the intro above, and unless noted in the specific service, List service calls support pagination of results. E.g., to get the third page of results with 20 results per page, send an HTTP request of the form (the specific path is only an example - the appropriate path is documented in each service API):

On success, a response with a "200 OK" HTTP status code is returned (note the pagination-info elements):

If no individual object/procedure/record instances are found, a response with a "200 OK" HTTP status code, followed by an empty list, is returned.

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.