Services Layer REST API
- Jessi Weithman
Your own scripts and programs can create, update, read, list and delete data in a CollectionSpace system, as well as integrate other systems with CollectionSpace, via its Services layer's REST API.
As a starting point, exploring this API's read and list requests can be as simple as entering various URLs into your web browser, and entering your username and password if prompted. You can also:
- Make ad hoc requests via a command-line tool such as cURL as a Client to CollectionSpace Services, or via a REST client add-on for your web browser.
- Write your own programs or scripts, or even your own entire front-end applications that use this API to interact with the data in a CollectionSpace system.
Overview
An excellent starting place for learning more about this REST API is the overview document, Common Services REST API documentation.
Requirements for access
In order to use the Services layer's REST API, your REST client application or browser plug-in, or your programming or scripting language, must be able to do the following:
- Make HTTP / HTTPS requests, using the GET method to read and list data, and (optionally) the POST, PUT and DELETE methods, respectively, to create, update, and delete data.
- Create and parse XML documents.
You will also need the username and password for an active user account on a CollectionSpace system, which has been granted the access permissions required by your program or script.
Individual service APIs
Acquisition
The Acquisition Service facilitates the set of activities that results in the addition of collection objects and associated information to the collections of the organization and their possible accession to the permanent collections.
Authorization
The authorization service provides the means to authorize a system entity to use system resources. It also provides control over access to those resources by system entities.
Authorization - Account
The Account service offers operations to manage a CollectionSpace account. To securely access the CollectionSpace services, an account for a user is required in the system. An account is associated with an identity. The identity could reside in the CollectionSpace Identity Provider (CS IdP) which is the default identity provider. It could also reside in a foreign identity provider, such as an institution's single sign-on (SSO) system (e.g. CalNet), or an OpenID provider.
Authorization - Permission
Manages the permissions associated with individual resources in the system.
Authorization - PermissionRole
Manages the permissions associated with a role.
Authorization - Role
Manages the roles defined in the system.
Batch Jobs
The Batch Job service allows the user to invoke batch jobs in a specific context, such as in the context of a single record, a list of records, or a group of records. Some batch jobs may also be invoked with no externally-provided context.Batch jobs are written in Java, and conform to a specific Java interface. These jobs have access to a broad cross-section of the services RESTful APIs; they can create, update, delete and search records; relate records; and perform many other actions. The results (output) of the batch jobs are returned as service invocation responses.
Blob
The Blob Service offers a RESTful API to perform CRUD (create, read, update, and delete) operations on file/document related information. Included in this information is the type and encoding of a file, and a reference to the location of the actual file/document bits.For accessing and managing metadata about media, see the Media Service.
CollectionObject
The CollectionObject service's primary operations support the creation and management of the information related to the collection objects in a museum, archive, or other collection repository. This service can be used to create, retrieve, update, and delete information about collection objects.
Common Services
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.
The general principles of this API are described first, followed by the common features of the CRUD+L operations.
Concept
Describes an entity for a concept, with structure among concepts.
Exhibition
The Exhibition Planning Service facilitates the planning and management of exhibitions. This procedure encompasses tracking the objects included in or considered for an exhibition, the people involved in the exhibition's activities, and the exhibition sections, if any.
API - to be added - is highly similar to that of other CollectionSpace procedures
Group
ID
The ID Service provides utility services around identifiers (IDs), the compound strings that are used to identify many of the entities throughout the CollectionSpace system. Generates new IDs. Stores and manages ID Patterns, which are used to generate and validate IDs conforming to those patterns.
API?
Intake
The Intake Service facilitates the set of activities that results in the initial intake of items into the organization. These activities typically involve recording the circumstances of the intake, such as information about the donor, depositor, or lender; and may also include valuation estimates and insurance information, condition information, and the like. Often, receipts are generated for person(s) or organization(s) that provided the objects.
Loan In
The Loan In Service represents the information around documenting and managing loans made into the organization; that is, the borrowing of objects for which the organization is responsible for a specific period of time and for a specified purpose, normally exhibition/display, but including research, conservation, education or photography/publication.
Loan Out
The Loan Out Service represents the information around documenting and managing the loan of objects to other organizations or individuals for a specific period of time and for a specific purpose, normally exhibition/display, but including research, conservation, photography and education.
Location
Describes an entity for a location, with structure among Locations (rooms in buildings). Relations provide, e.g., formal description of where a CollectionObject is, over time.
Media
The Media Service provides basic support for managing metadata around media. This includes data about creation, publishing and rights; dimensions (resolution, time length, etc.), and similar attributes.For accessing and managing physical media (e.g. binary files) and media derivatives, see the Blob Service.
Movement
The Movement Service manages information around the movement of a CollectionObject - an instance of location change. This includes location changes resulting from movements between storage locations, such as between rooms or shelves. Movement will have an associated reason, which will often be another event entity, such as an exhibition, a loan, or a conservation action.
Object Exit
Organization
Describes an entity for an organization or any contextually-meaningful organizational unit. Organizations may be structured so that there are organizational units (also departments, subdivisions) within an Organization. For example, there may be a Conservation Department within a museum; or museums and organized research units (ORUs) within a university. An organization may be modeled in multiple hierarchies, e.g., structural vs. financial within a larger institution, and also in various membership relations (e.g., an organization of regional museums).
Person
Captures information about a known person referenced in the system. This models actors in the management of collections (including collections managers, donors, conservators, etc.), as well as persons (real or imaginary) that are depicted or referenced in artwork, reference materials, annotations, etc.
Place
Describes an entity for a place, with structure among places.
Relation (aka Relationship)
The Relationship Service manages and documents the relationships between and among object, procedural, and organizational records.
Reporting
The Reporting service allows the user to invoke a report defined in an external authoring tool, to be executed in a specific context. The results (output) of the report are returned as the service invocation response.
Storage Location
See Services Layer REST API#Location.
Vocabulary
A vocabulary is a collection of controlled terms. These may be unorganized, an ordered list, a taxonomic tree, or a relational graph (ontology). These may be variously called term lists, (controlled) vocabularies, taxonomies, ontologies, or authorities, among other names. The Vocabulary has terms with individual information including provenance and bibliographic references, and these terms are related in some structure.
Alphabetically-ordered links to API documentation (also shown at left) for accessing individual services within the CollectionSpace Services layer: