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 resources, plus list operations such as list all, keyword search, and partial term matching) 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 Services Layer REST API.

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 uniform 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 parts, following the principles articulated in the CollectionSpace Services Architecture. (A small number of services return a schema consisting only of a single part.)
• The list operations return lists of multiple resources. The list operations of most services use a second, uniform 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 that additional fields be added to the returned results, but this functionality is not yet supported. 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 resources.
• HTTP GET requests are used to read resources. They are also used in list operations that may return multiple items, such as list all, keyword search and partial term matching (term suggestion / term completion).
• HTTP PUT requests are used to update (change) resources.
• HTTP DELETE requests are used to delete resources.