Common Services REST API documentation

Owned by Jesse Martinez
Last updated: Feb 21, 2017 by Tom JonesVersion comment
34 min read

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.
On This Page

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:

Payloads for individual records

Payloads for individual records in most CollectionSpace services are extensible. Extensibility is provided by bundling multiple parts for each record in Create, Read and Update operations: a "core" part, a "common" part, and zero or more optional extension parts. Details regarding this:

  • With each service that supports extensible schema, the payloads you will send and receive for individual resources, in Create, Read and Update operations, are XML documents, with a Content-Type header of application/xml. (Note that Delete operations don't exchange a payload in the body of the request.) Each field in an object or procedural record is usually represented by a corresponding element in that XML document.

    Payloads consist of one or more parts, each contained within separate XML elements:
    • Each part is associated with one of the layered schemas, as described in the Schema Extension documentation:
    • There will be:
      • One core part. This part contains metadata about the record, such as when, and by whom, it was created and last modified. Fields in this part are set internally when a record is created, and the updatedAt and updatedBy fields are refreshed each time the record is updated. The core part is read-only; if an incoming payload includes this part, its values will be ignored.
      • One common part. This part contains the set of standard (or "common") fields for the CollectionSpace record of that type (e.g. CollectionObjects, Acquisitions, LoansOut ...)
      • Zero or more optional extension parts. Each extension part, if any, will contain a set of new fields that extend the standard CollectionSpace record type. Extension parts may in turn be associated with a "domain" (containing fields defined by a community of museums or a similar body, and often associated with a specific discipline such as fine arts, anthropology, or botany) or be a "local" part (containing fields unique to your own museum).
    • Some response payloads may also return an additional part or parts, such as a part containing information about related resources.

Suggested addition

Add: "Payload parts are denoted by the prefix 'ns2:' (for example, <ns2:intakes_common></ns2:intakes_common>)"? Is this prefix used consistently throughout the service payloads?

 

  • With each service that does not support extensible schema, or where the request or response contains the payload only from a single schema, the payloads that you will send and receive for individual resources, in Create, Read and Update operations, will typically be an XML document, with a Content-type header of application/xml. Each field in an object or procedural record is usually represented by a corresponding element in that XML document.

    Some notable examples of services that do not support extensible schema are the Account service, Authorization service, and the ID service. List operations also follow this model (see below).

    (In the case of just the ID service, payloads of text/plain are currently returned by one Read operation: that of retrieving new IDs. This may later change to an XML-based payload, for uniformity with other services.)

Payloads for lists

When you directly request a list of resources, or when a list of resources is returned in response to a search, partial term match, request for related authorities, or similar operations, the payload you will receive will be an XML document, with a Content-type header of application/xml.

Each item in the list will be contained within an 'item'-type element, whose name will vary.

 

 

 

 

 

Unknown macro: {multi-excerpt} Each item in a list contains compact, summary information for each resource. This summary information will typically contain one or two displayable fields, as well as the identifier and URL for retrieving the full record for that item.

 

 

 

 

 

For more information on lists and list payloads, see List results, pagination controls and search.

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 an individual record (or resource), 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 a record (or resource), 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 multivalued, multivalue, or repeating) fields and field groups.

For some record types, it is specified that:

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

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:

As shown in the example above, it is permissible to create or update an instance of a repeatable field with a value that is empty (blank).

Tenant name in URN; other changes?

Note that the urn now includes a segment that indicates the tenant, as in this example:

urn:cspace:core.collectionspace.org:vocabularies:name(conditionfitness):item:name(unsuitable)'Unsuitable'

('core' is the tenant in this example.)

Has anything else changed?

A repeatable group of fields is represented in payloads in the form of a grandparent "list" field, which acts solely as a container; a parent "group" field, which also acts solely as a container, and zero or more instances of the fields within that group. Example (to show structure only; this is not an example from any CollectionSpace record type):

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 an authentication token, consisting of the userid and password Base64 encoded as follows:

Where QWxhZGRpbjpvcGVuIHNlc2FtZQ== is an example of userid:password in Base64 encoded form. Note that in the authentication token, the userid and password are delimited (separated) by a colon character (:), prior to being Base64 encoded. Refer to HTTP Basic Authentication for more details.

In a future release of the CollectionSpace system, the calling application may also be required to provide an authorized application ID.

List results, filtering, pagination controls, sorting and search

List results

All REST services allow you to obtain lists of items. Each item in a list contains compact, summary information for each resource. This summary information will typically contain one or two displayable fields, as well as the identifier and URL for retrieving the full record for that item.

In the future, it may be possible to configure and/or more flexibly specify the fields returned in summary information, for export and other purposes.

List pagination

Most REST services that provide lists of results also support pagination of the results. Rather than receiving many thousands of records upon a GET request for, say, cataloging records, you can instead request a single "page" of the list, containing a smaller subset of those records, and then you can 'page through' the entire list.

You can control how many records are returned per page, and which page of records to retrieve, by adding query parameters onto your GET request:

  • pgSz indicates the number of results to return per page.
    • If pgSz is not provided, the default behavior will return 40 items on each page of the list results (with the potential ability in the future to be able to configure this centrally and/or per service).

    • pgSz has a maximum value of 1000 (should probably support configuration of this as well).

      This maximum needs to be verified. I could not find a maximum constant or configured value, and was able to retrieve 2000 person items on Nightly by setting pgSz=2000, with a total dataset of 2064 such records. (See CSPACE-4970.)

    • Setting pgSz=0 will return up to the maximum number of items, on a single page. (When large numbers of items will be returned, the response to a pgSz=0 request may be somewhat slow.)
  • pgNum indicates the page number to return. This leverages the pgSz value to produce the starting offset for the returned results.
    • If pgNum is not provided, the default behavior will return the first page (page 0, as discussed below) of the list results.
    • Pages are zero-based; you can request the first page of results via pgNum=0, the second page via pgNum=1, and so on.

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 <itemsInPage> element reflects the total number of items in the current page.
  • The <totalItems> element reflects the total number of items found for the list or search query.
  • The <fieldsReturned> element identifies the fields returned within each list item. The value of that element consists of a pipe-delimited ("|") list of field names.

Filtering on workflow state

Most REST services that provide lists of results support filtering on workflow state.

By default, all records are returned in list results, regardless of workflow state. Optionally, you can specify that records matching a particular workflow state, or states, will be excluded from list results.

The sole workflow state on which you can currently filter records is the "soft" deleted state. A record that has been "soft" deleted has been marked for deletion, but the record and its data still exist.

To exclude records in the "soft deleted" state from list results, so that only active (non-deleted) records are returned, add the following query parameter to your GET request:

(In addition, individual records in the "soft deleted" state can also be excluded from being returned from results. See Read an object/procedure/record instance for details.)

Sorting

Most REST services that provide lists of results also support sorting of the results. You can specify the field on which to sort by adding query parameters onto your GET request:

sortBy indicates the field on which to sort. The value of this parameter takes a schema name, a colon (':') as a delimiter, and a field name within that schema, as defined by the services. Examples:

The second example above sorts on a custom field, within a museum's local schema for a collection object - in this hypothetical example named "collectionobjects_local".

By default, sorted results are returned in ascending order: from first to last. "Empty" (null or empty string) values are returned in sort order before non-empty values. To sort in descending order, add "+DESC" to the end of the field name. Example:

To sort on more than one field, separate each sort field with ,+. Example:

Records will be ordered by the first sort field provided; then, within that ordering, by the second sort field, and so on. In the example above, records will first be sorted by their location date fields in descending order; then, in cases where there are multiple records with identical location dates, they will be sorted by their movement note fields in ascending order.

In contrast with pagination details, details regarding the sort order used are not currently returned in the list results. These are scheduled to be added in a future release.

Records will be ordered by the collation (ordering) behavior of your database system. This may, in turn, be based on collation and language settings for your database, your operating system, or both. Collectively, these settings may determine whether (in the Roman alphabet, for instance) uppercase and lowercase characters (like "A" and "a") are ordered together or separately; how characters with diacritical marks are ordered, relative to similar characters without those marks; and how punctuation and other special characters are handled when ordering. By adjusting those settings, you may also be able to adjust how records in CollectionSpace are ordered, when you use the ?sortBy= query parameter.

Search (query)

Some services support search (query) methods to return matching 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, the query parameter "kw=term" specifies the keyword on which to search.
  • For those services (primarily Authorities and Vocabularies) that support partial term matching (aka term suggestion or term completion search), the query parameter "pt=term" specifies the partial term to match.
  • For those services (primarily Authorities and Vocabularies) that support termStatus filtering (aka filtering results based upon termStatus values), the query parameter "ts=term1|term2" specifies the list of terms to match. Note that the separator ('|') is URL encoded as %7C.

There have been discussions about different profilesof information that would be defined (probably in configuration) and specified as query parameter to the List operation. In addition, we may support a facility to include extra, specific fields (from any of the common, domain, or local schema parts) for each instance in the list-results information returned. Once this functionality has been resolved, it will be documented here.

Related records

In a CollectionSpace system, with only a few exceptions, any two records can be related to one another. Some representative examples:

  • Multiple Cataloging / CollectionObject records can be related to an Intake, Acquisition, Loan In, Loan Out, or Object Exit record.
  • Similarly, multiple Location/Movement/Inventory records can be related to a Cataloging / CollectionObject record.

Some records can also be hierarchically related to one another. Some representative examples:

  • 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
    Quebec

    Canada

    Ontario

    -

    Canada

    Quebec

    -

 

 

 

 

 

Unknown macro: {multi-excerpt} 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.

 

 

 

 

 

See List related records for more details.

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

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 a collection of service resources or sub-resources (e.g. ../collectionobjects/ or ../personauthorities/{csid}/persons/). The RESTful metaphor is that of creating a new record within a container, or 'bucket', of records of that type.

The body of your Create request contains the data that will be used to create a new record. In most cases, you'll be sending an XML document consisting of one or more parts, with each part contained within its own XML element.

An example of a Create request to the CollectionObject service follows below. See each individual service's API documentation for further details:

multipart request for Create

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

Any XML document(s) included in your Create request must be 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 (record format); 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:

response for Create

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:

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

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 a specific instance of a 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):

request for Read

Most read service calls accept a single, optional query parameter:

request for Read, excluding "soft" deleted records

If this parameter is included, a record that has been "soft" deleted will not be returned by the Read request. Instead, a 404 Not Found status code will be returned in the response.

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.

multipart response for Read

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:

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 ?wf_deleted=false parameter is included in the Read request, this error may also be returned if the record exists but has been "soft" deleted.)

500

Internal Server Error

A service error prevented the resource from being read.

Update an object/procedure/record instance

Updates an individual object/procedure/record instance, specified by its CollectionSpace ID (CSID) as may be returned by Create, or by 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 of a resource or sub-resource, qualified with a CollectionSpace ID (CSID) value (e.g. ../collectionobjects/{csid} or ../personauthorities/{csid}/persons/{csid}).

The body of your Update request contains the data that will be used to update the existing record. In most cases, you'll be sending an XML document consisting of one or more parts, with each part contained within its own XML element.

An example of an Update request to the CollectionObject service, to update the contents of the record whose CollectionSpace ID (CSID) is 850161ed-466c-4af2-bc45, follows below. See each individual service's API documentation for further details:

multipart request for Update

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

Any XML document(s) included in your Update request must be a valid XML representation of the associated object/procedure/record whose contents you wish to update. This may be a sparse payload, containing only selected fields. Each service has a different schema (record format); for details, please see the individual service's documentation.

As a general rule, if the XML document(s) included in the payload of your Update request include one or more elements that have child elements, the update will completely replace (i.e. overwrite) the existing child elements with the new child elements, if any, you are sending. This means, for example, to update the contents of a multi-valued field, you will send an update request containing a new set of values for that field. To remove all of the values from a multi-valued field, you will send an update request containing no values for that field. For any per-service exceptions to this behavior, 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 the same as for the standard read operation; see Read an object/procedure/record instance.

multipart response for Update

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:

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

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.

This is a "hard" delete, which removes the record and all of its data from the CollectionSpace system. Unless an export or backup has previously been performed, the record and its data can be considered permanently deleted and unrecoverable.

To perform a "soft" delete, which simply marks a record for deletion, while retaining the record and its data, see Update workflow state of an object/procedure/record instance.

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):

request for Delete

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:

response for Delete

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:

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

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.

 

 

 

 

 

Unknown macro: {multi-excerpt} Each item in a list contains compact, summary information for each resource. This summary information will typically contain at least one or two displayable fields, as well as the identifier and URL for retrieving the full record for that item.

 

 

 

 

 

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):

request for List all

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):

request for List partial

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

response for Get all

The names of the root element and of the item elements in the list may vary between services. As of CollectionSpace version 1.9, most services return abstract-common-list as the name of the root element in the list and list-item as the name of each item element in the list.

If no individual object/procedure/record instances are found, a response with a "200 OK" HTTP status code, containing pagination information and an empty list - a list with only a root element, but no child elements - 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.

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

This section is in process and is currently incomplete.

Searches on one or more keywords, and returns summary information about all instances of the associated resources which are matched by those keywords.

Instances for which the authenticated user does not have read privileges, will not be returned in results.

Verify whether this assertion is currently accurate for keyword search.

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.

Keyword searches:

Verify all of the following with Richard. Explain further (e.g. "short words") where needed. Identify whether values in repeatable fields can be searched, either as repeatable single scalar fields, or with either or both of the upcoming services paradigms for implementing repeatable groups of fields. Identify any significant database system-specific differences, such as between PostgreSQL and MySQL.

  • Are conducted within the full text of all fields.
  • Are case-insensitive.
  • When multiple keywords are provided, are carried out as though a Boolean OR is present between each keyword.
  • Will not match a database-dependent list of stopwords. (See, for example, Issue CSPACE-807.)
  • Will not match short words.

Calling method and Arguments

Keyword search is invoked as an HTTP GET method on the primary resource, including a specific query parameter (kw=) to indicate that a keyword search is being performed, and providing a list of zero or more keywords to be used in the search as arguments to that query parameter.

Send an HTTP request of the form (the specific path is only an example - the appropriate path is documented in each service API):

request for Keyword search

To search on multiple keywords, add a plus sign ("+") between each keyword:

request for Keyword search on multiple keywords

Query parameters may follow the previous path component of the URL, either with or without a trailing slash: .../collectionobjects/?kw= keyword and .../collectionobjects?kw= keyword are both accepted as valid requests.

On success, a response with a "200 OK" HTTP status code is returned. The payload that is returned from a keyword search is identical to the payload returned from a List All request.

Add example below. Verify and describe the interaction between pagination and search.

response for Keyword search

If no object/procedure/record instances match the keyword(s) provided, 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.

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.

Need to add error responses here.

Advanced Search for object/procedure/record instances

This section is in process and is currently incomplete.

Searches using a provided search expression and returns summary information about all instances of the associated resources which are matched by that expression.

Instances for which the authenticated user does not have read privileges, will not be returned in results.

Verify whether this assertion is currently accurate for advanced search.

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

Advanced search is invoked as an HTTP GET method on the primary resource, including a specific query parameter (as=) to indicate that an advanced search is being performed, and providing a search expression as the argument to that query parameter.

The search expression must be:

  • A valid NXQL expression. (NXQL is the schema-aware query language used with CollectionSpace's Nuxeo repository, and its expressions are similar to standard SQL SELECT statements. See Nuxeo's NXQL search documentation.)
  • URL encoded.

Send an HTTP request of the form (the specific path is only an example - the appropriate path is documented in each service API) shown in these representative examples:

request for advanced search within the 'loanInPurpose' field in Loan In records, for case-insensitive values containing 'research'

Written with easier-to-read, non-URL encoded values:
?as=loansin_common:loanPurpose ILIKE '%research%'

request for advanced search within the 'loanInNumber' field in Loan In records, for case-sensitive values starting with 'LI2012'

Written with easier-to-read, non-URL encoded values:
?as=loansin_common:loanInNumber LIKE 'LI2012%'

request for Advanced search within the 'depositor' field in Intake records, providing a full refName for an authority term to be searched for in that field

Written with easier-to-read, non-URL encoded values: ?as=intakes_common:depositor="urn:cspace:core.collectionspace.org:personauthorities:name(person):item:name(JohnDoe1327373674139)'John Doe'"
(the double quote marks around the refName are required in this instance, to enclose the single quote marks in the display name portion of the refName)

request for Advanced search in Cataloging / CollectionObject records, for records updated within a specific date range

Written with easier-to-read, non-URL encoded values:
?as=collectionspace_core:updatedAt >= TIMESTAMP "2012-01-17T00:00:00" AND collectionspace_core:updatedAt <= TIMESTAMP "2012-01-31T23:59:59"

request for Advanced search within the 'date' structured date field in Media records, for dates within a specific date range

Written with easier-to-read, non-URL encoded values:
?as=media_common:dateGroupList/*/dateEarliestScalarValue >= TIMESTAMP "2011-02-17T00:00:00" AND media_common:dateGroupList/*/dateLatestScalarValue <= TIMESTAMP "2011-03-31T23:59:59"

For more details and additional examples, see the CollectionSpace documentation on advanced search.

Query parameters may follow the previous path component of the URL, with or without a trailing slash: .../collectionobjects/?as= search_expression and .../collectionobjects?as= search_expression are both accepted as valid requests.

On success, a response with a "200 OK" HTTP status code is returned. The payload that is returned from an advanced search is identical to the payload returned from a List All request.

response for Advanced search

If no object/procedure/record instances match the search expression provided, 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.

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.

Need to add error responses here.

Partial Term Matching for object/procedure/record instances

This section is in process and is currently incomplete.

Searches on a partial term. (This functionality may also sometimes be described as term suggestion or term completion.) Returns summary information about all instances of the associated resource that are matched by the partial term.

As an example, a partial term search on ally might match on Ally McBeal, June Ally son and W ally Van.

Note that, currently, partial term matching functionality is supported only by selected services:

  • The Vocabulary service.
  • The authority services (e.g. Person, Organization).

Instances for which the authenticated user does not have read privileges, will not be returned in results.

Verify whether this assertion is currently accurate for partial term matching.

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

Partial term matching is invoked as an HTTP GET method on the primary resource, including a specific query parameter and arguments to indicate that a partial term match is being performed, and providing the terms to be used in the match.

Send an HTTP request of the form (the specific path is only an example - the appropriate path is documented in each service API):

request for Partial term matching

If the service offers access to a sub-resource, such as to the individual Organizations in an Organization Authority, partial term matching on the subresource uses a similar request syntax:

request for Partial term matching on sub-resources

On success, a response with a "200 OK" HTTP status code is returned. The payload that is returned from a partial term match is identical to the payload returned from a List All request:

Add example below. Verify and describe the interaction between pagination and search.

Mention and provide example(s) of the use of anchors and wildcards in partial term matching requests. For a look at how these features work, conceptually, please see /wiki/spaces/collectionspace/pages/666274082.

response for Partial term matching

If no object/procedure/record instances match the partial term provided, 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.

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

This section is in process and is currently incomplete.

Filters out returned terms based upon termStatus values. This may be combined with other searches, and so returns the same list results as other list and search operations. The parameter may specify one or more string values, corresponding to values set in the termStatus field of Authority items.

For those items that would otherwise be returned from the list or search operation, all items will be returned except those that have a termStatus matching any of the specified filter values. Those values will be excluded from the results.

Note that, currently, termStatus filtering functionality is supported only by selected services:

  • The Vocabulary service.
  • The authority services (e.g. Person, Organization).

Calling method and Arguments

Term status filtering is applied to search and list operations, and so is invoked as the corresponding HTTP GET methods on the associated resources:

request for all person terms that have not been marked as rejected
request for all person terms that match the partial term, and have not been marked as rejected

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.

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.

Related Authority References for object/procedure/record instances

Retrieves and returns all references to authorities found in an individual object or procedural record. (Stated another way, retrieves the authority terms used in a record, including the fields in which they are used, and provides links for accessing detailed information about each term.)

Instances for which the authenticated user does not have read privileges, will not be returned in results.

Verify whether this assertion is currently accurate for related authority references.

Calling method and Arguments

A call to retrieve related authority references is invoked as an HTTP GET method on the primary resource, followed by the "authorityrefs" path component. Send an HTTP request of the form (the specific path is only an example - the appropriate path is documented in each service API):

request for Related authority references

On success, a response with a "200 OK" HTTP status code is returned, with a payload similar to the following example:

response for Related authority references

In the above example, the 'depositor' field of the specified Intake resource has been identified as containing the term "James Adams", which in turn comes from a specified Person Authority. Information about that term can then be accessed via the path specified in the 'uri' field.

Some multivalued fields may contain more than one term. In those cases, multiple list items - one for each term found - will be returned for those fields.

If no related authority references are found in the record, 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.

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 term instances

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.

Instances for which the authenticated user does not have read privileges, will not be returned in results.

Verify whether this assertion is currently accurate for related object references (probably not).

Calling method and Arguments

A call to retrieve related authority references is invoked as an HTTP GET method on the authority item resource, followed by the "refObjs" path component. Send an HTTP request of the form (the specific path is only an example - the appropriate path is documented in each service API):

request for Related authority references

On success, a response with a "200 OK" HTTP status code is returned, with a payload similar to the following example:

response for object references

In the above example, the 'depositor' field of the specified Intake resource has been identified as containing the term 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 is indicated as well as the uri.

If an object has multiple references to a given term, multiple entries for that referring object 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."

request for procedure-only references

If no related authority references are found in the record, 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.

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 object 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 objectreferences 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 objectreferences was requested does not exist. Note that if the resource does exist, but currently contains no object 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 object references, or the relevant resource from which that list was requested, from being read.

Read workflow state of an object/procedure/record instance

Retrieves and returns the workflow state of an individual object or procedural record.

Calling method and Arguments

A call to retrieve the workflow state is invoked as an HTTP GET method on an individual object/procedure/record instance, specified by its CollectionSpace ID (CSID), and followed by the "workflow" path component. Standard authentication applies, and user must have read privileges for workflow state.

Read request for Workflow state

On success, a response with a "200 OK" HTTP status code is returned, with a payload similar to the following example:

response to Read request for Workflow state

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

Updates the workflow state of an individual object or procedural record.

Versions 2.3 and later

In versions 2.3 and later, any particular type of record may have a specific set of workflow states and associated transitions to those workflow states (described collectively as a "lifecycle"). Currently:

  • Most records in CollectionSpace have a default set of workflow states and transitions.
  • Location/Movement/Inventory records have a similar, 'locking' set of workflow states and transitions, that also includes a "lock" transition to a "locked" state. Records in a locked state can't be edited, or (generally) have their workflow state further changed, making it feasible to "hard save" selected records for auditing purposes.

You can find the workflow states and state transitions available for records that use either the default ("cs_default") or 'locking' ("cs_locking") lifecycles in this file.

Calling method and Arguments

A call to update the workflow state is invoked as an HTTP PUT method on an individual object/procedure/record instance, specified by its CollectionSpace ID (CSID), followed by the "workflow" path component and a path component for a specific transition to a different workflow state. Standard authentication applies, and user must have Update privileges for the type of transition being requested. No payload is sent in the body of this PUT request.

An example of an Update request to the CollectionObject service, to update the workflow state of the CollectionObject record whose CollectionSpace ID (CSID) is 850161ed-466c-4af2-bc45 to the workflow state of deleted, follows below. See each individual service's API documentation for further details:

request to invoke 'delete' workflow transition, to set a record to the 'deleted' workflow state

On success, a response with a "200 OK" HTTP status code is returned, with a payload similar to the following example:

response to invoking 'delete' workflow state transition

An example of an Update request to the CollectionObject service, to update the workflow state of the CollectionObject record whose CollectionSpace ID (CSID) is 850161ed-466c-4af2-bc45 to the workflow state of project (i.e. active), follows below. See each individual service's API documentation for further details:

request to invoke 'undelete' workflow transition, to set a record to the 'project' workflow state

On success, a response with a "200 OK" HTTP status code is returned, with a payload similar to the following example:

response to invoking 'undelete' workflow state transition

An example of an Update request to the Movement service, to update the workflow state of the Location/Movement/Inventory record whose CollectionSpace ID (CSID) is ea90563a-9b34-4347-a3ab to the workflow state of locked ("hard saved"), follows below.

request to invoke 'lock' workflow transition, to set a record to the 'locked' workflow state
response to invoking 'lock' workflow state transition

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:

  • project This represents an active record, and is the default workflow state for a newly-created record.
  • deleted This represents a "soft deleted" record; i.e. a record that has been marked for deletion. The record and all of its data still exist within the CollectionSpace system, although the record may not be returned via some GET requests. (See Filtering on workflow state for details.) The record can be "undeleted" by having its workflow state updated back to the project state.

Other workflow states may be added in future releases.

Calling method and Arguments

A call to update the workflow state is invoked as an HTTP PUT method on an individual object/procedure/record instance, specified by its CollectionSpace ID (CSID), and followed by the "workflow" path component. Standard authentication applies, and user must have update privileges for workflow state.

You can update a record to a different workflow state by specifying that state in the <currentLifeCycleState> element in the payload of your UPDATE request.

An example of an Update request to the CollectionObject service, to update the workflow state of the record whose CollectionSpace ID (CSID) is 850161ed-466c-4af2-bc45 to the workflow state of deleted, follows below. See each individual service's API documentation for further details:

request to Update workflow state

On success, a response with a "200 OK" HTTP status code is returned, with a payload similar to the following example:

response to Update Workflow state

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

This section is an early placeholder; it needs considerable expansion and refinement.

Unknown macro: {multi-excerpt-include}

List related records via the Relations service

For a rich set of REST API calls to return related records via the Relations service, please see Relationship Service RESTful APIs.

These calls all return lists of Relation records, the "linking" records that relate any two other types of records.

List related records via rtSbj and rtObj

To list records of a specific type that are related to a particular record, specified by its CollectionSpace ID (CSID), add the rtSbj or rtObj query parameter to the call.

For example, to list Movement records related to the record (which can be of nearly any type) specified by CSID 850161ed-466c-4af2-bc45, where that specified record is the subject of the relationship:

request to obtain Movement records related to a specified record, the latter as relationship subject

Similarly, to list Movement records related to the record specified by CSID 850161ed-466c-4af2-bc45, where that record is the object of the relationship:

request to obtain Movement records related to a specified record, the latter as relationship object

Both of the above requests return lists of Movement records.