Versions Compared

Old Version 3

changes.mady.by.user Tom Jones

Saved on

compared with

New Version Current

changes.mady.by.user Megan Forbes

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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:

...

Note
titleSuggested 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.)

...

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

 

 

 

 

Wiki Markup
{multi-excerpt:list-item-summary-information}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.{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.

...

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:

true
Code Block
controls
<acquisitionSources>
  <acquisitionSource>urn:cspace:org.collectionspace.demo:personauthority:id(TestPersonAuthority):item:name(SallyKRide)'Sally K. Ride'</acquisitionSource>
  <acquisitionSource>urn:cspace:org.collectionspace.demo:personauthority:id(TestPersonAuthority):item:name(RobertLCrippen)'Robert L. Crippen'</acquisitionSource>
  <acquisitionSource></acquisitionSource>
  ...
</acquisitionSources>

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

...

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

Code Block
controlstrue

<aGroupList>
  <aGroup>
    <field1>value</field1>
    <field2>value</field2>
  </aGroup>
  <aGroup>
    <field2>value</field2>
    <field3>value</field3>
    <field5>value</field5>
  </aGroup>
  ...
</aGroupList>

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.

...

Code Block
WWW-Authenticate: Basic realm="org.collectionspace.services"


In response, the user agent could send an authentication token, consisting of the userid and password Base64 encoded as follows:

Code Block
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==


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. Anchorlistslists

List results, filtering, pagination controls, sorting and search

...

Tip
nameTip

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:

...

  • 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

    -

 

 

 

 

 

Wiki Markup
{multi-excerpt:api-calls-to-retrieve-related-records}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.{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. Anchorcrud-plus-listcrud-plus-list

Standard CRUD+L APIs for CollectionSpace services

...

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
Code Block
controlstrue
title
POST /cspace-services/collectionobjects HTTP/1.1
Content-Type: application/xml
Content-Length: nnnn
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<document name="collectionobjects">
<ns2:collectionobjects_common xmlns:ns2="http://collectionspace.org/services/collectionobject">
  <objectNumber>objectNumber-1266005065536</objectNumber>
  <briefDescription>
     Papier mache bird cow mask with horns, painted red with black and yellow spots.
     Puerto Rico. ca. 8&amp;quot; high, 6&amp;quot; wide, projects 10&amp;quot; (with horns).
  </briefDescription>
  <objectName>objectName-1266005065536</objectName>
  ...
</ns2:collectionobjects_common>
<ns2:collectionobjects_naturalhistory
     xmlns:ns2="http://collectionspace.org/services/collectionobject/domain/naturalhistory">
  <nh-string>test-string</nh-string>
  <nh-int>999</nh-int>
  <nh-long>9999</nh-long>
</ns2:collectionobjects_naturalhistory>
</document>

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

...

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
Code Block
controlstrue
title
HTTP/1.1 201 Created
Content-Type: application/xml
Location: https://demo.collectionspace.org/cspace-services/collectionobjects/a4b65c82-0eb8-41ec-8936
Content-Length: nnnn
...

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.

...

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

...

controlstrue
titlerequest for Read

):

Code Block
GET /cspace-services/collectionobjects/{csid} HTTP/1.1

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

Code Block
controlstrue
titlerequest for Read, excluding "soft" deleted records
GET /cspace-services/collectionobjects/{csid}?wf_deleted=false HTTP/1.1

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.

...

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.

title
Code Block
controlstrue
multipart response for Read
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: nnnn
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<document name="collectionobjects">
<ns2:collectionspace_core xmlns:ns2="http://collectionspace.org/collectionspace_core/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <updatedAt>2011-08-02T21:08:33Z</updatedAt>
    <createdAt>2011-07-29T18:03:56Z</createdAt>
    ...
</ns2:collectionspace_core>
<ns2:collectionobjects_common xmlns:ns2="http://collectionspace.org/services/collectionobject">
  <objectNumber>objectNumber-1266005065536</objectNumber>
  <briefDescription>
     Papier mache bird cow mask with horns, painted red with black and yellow spots.
     Puerto Rico. ca. 8&amp;quot; high, 6&amp;quot; wide, projects 10&amp;quot; (with horns).
  </briefDescription>
  <objectName>objectName-1266005065536</objectName>
  ...
</ns2:collectionobjects_common>
<ns2:collectionobjects_naturalhistory
     xmlns:ns2="http://collectionspace.org/services/collectionobject/domain/naturalhistory">
  <nh-string>test-string</nh-string>
  <nh-int>999</nh-int>
  <nh-long>9999</nh-long>
</ns2:collectionobjects_naturalhistory>
</document>

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.

...

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
Code Block
controlstrue
title
PUT /cspace-services/collectionobjects/850161ed-466c-4af2-bc45 HTTP/1.1
Content-type: application/xml
Content-Length: nnn
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<document name="collectionobjects">
<ns2:collectionobjects_common
     xmlns:ns2="http://collectionspace.org/services/collectionobject">
  <objectNumber>updated-objectNumber-1266003498657</objectNumber>
  <objectName>updated-objectName-1266003498657</objectName>
  ....
</ns2:collectionobjects_common>
</document>

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

...

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.

title
Code Block
controlstrue
multipart response for Update
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: nnnn
 
 
<document name="collectionobjects">
<ns2:collectionspace_core xmlns:ns2="http://collectionspace.org/collectionspace_core/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <updatedAt>2011-08-02T23:15:06Z</updatedAt>
    ...
</ns2:collectionspace_core>
<ns2:collectionobjects_common
    xmlns:ns2="http://collectionspace.org/services/collectionobject"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="...">
  <objectNumber>updated-objectNumber-1266003498657</objectNumber>
  <title>atitle</title>
  <briefDescription>Papier mache bird cow mask with horns, painted red with black and yellow spots.
    Puerto Rico. ca. 8&amp;quot; high, 6&amp;quot; wide, projects 10&amp;quot; (with horns).
  </briefDescription>
  <objectName>updated-objectName-1266003498657</objectName>
  ...
</ns2:collectionobjects_common>
<ns2:collectionobjects_naturalhistory
     xmlns:ns2="http://collectionspace.org/services/collectionobject/domain/naturalhistory">
  <nh-string>test-string</nh-string>
  ...
</ns2:collectionobjects_naturalhistory>
</document>

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.

...

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
Code Block
controlstrue
title
DELETE /cspace-services/collectionobjects/{csid} HTTP/1.1

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
Code Block
controlstrue
title
HTTP/1.1 200 OK
Content-Length: 0
...

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 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.

 

 

 

 

 

unmigrated-inline-wiki-markup

{multi-excerpt:list-item-summary-information}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.{multi-excerpt}

 

 

 

 

 

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.

...

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
Code Block
controlstrue
title
GET /cspace-services/collectionobjects HTTP/1.1

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
Code Block
controlstrue
title
GET /cspace-services/collectionobjects?pgSz=20&pgNum=2 HTTP/1.1

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

response for Get all
Code Block
controlstrue
title
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: nnnn
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:abstract-common-list xmlns:ns2="http://collectionspace.org/services/jaxb">
  <pageNum>2</pageNum>
  <pageSize>20</pageSize>
  <totalItems>53</totalItems>
  <fieldsReturned>objectNumber|objectName|title|responsibleDepartment|uri|csid</fieldsReturned>
  <list-item>
    <objectNumber>objectNumber-1304508705716</objectNumber>
    <objectName/>
    <title>title-1304508705716</title>
    <responsibleDepartment/>
    <uri>/collectionobjects/18acadbf-8e89-4520-a1f9</uri>
    <csid>18acadbf-8e89-4520-a1f9</csid>
  </list-item>
  <list-item>
    <objectNumber>objectNumber-1304508708473</objectNumber>
    <objectName/>
    <title>title-1304508708473</title>
    <responsibleDepartment/>
    <uri>/collectionobjects/c3deb7f9-3882-46d1-b79e</uri>
    <csid>c3deb7f9-3882-46d1-b79e</csid>
  </list-item>
  ...
</ns2:abstract-common-list>

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.

...

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
Code Block
controlstrue
title
GET /cspace-services/collectionobjects?kw=cucurbita HTTP/1.1

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

request for Keyword search on multiple keywords
Code Block
controlstrue
title
GET /cspace-services/collectionobjects?kw=whetstone+sharpening+sharpen HTTP/1.1


Info

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.

...

Note

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


Code Block
controlstrue
titleresponse for Keyword search
HTTP/1.1 200 OK
...

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.

...

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:

controls
Code Block
truetitlerequest for advanced search within the 'loanInPurpose' field in Loan In records, for case-insensitive values containing 'research'
GET /cspace-services/loansin?as=loansin_common%3AloanPurpose%20ILIKE%20%27%25research%25%27

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

true
Code Block
controls
titlerequest for advanced search within the 'loanInNumber' field in Loan In records, for case-sensitive values starting with 'LI2012'
GET /cspace-services/loansin?as=loansin_common%3AloanInNumber%20LIKE%20%27LI2012%25%27

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

true
Code Block
controls
titlerequest 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
GET /cspace-services/intakes?as=intakes_common%3Adepositor%3D%22urn%3Acspace%3Acore.collectionspace.org%3Apersonauthorities%3Aname%28person%29%3Aitem%3Aname%28JohnDoe1327373674139%29%27John+Doe%27%22

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)

true
Code Block
controls
titlerequest for Advanced search in Cataloging / CollectionObject records, for records updated within a specific date range
GET /cspace-services/collectionobjects?as=collectionspace_core%3AupdatedAt+%3E%3D+TIMESTAMP+%222012-01-17T00%3A00%3A00%22+AND+collectionspace_core%3AupdatedAt+%3C%3D+TIMESTAMP+%222012-01-31T23%3A59%3A59%22

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"

true
Code Block
controls
titlerequest for Advanced search within the 'date' structured date field in Media records, for dates within a specific date range
GET /cspace-services/media?as=media_common%3AdateGroupList%2F*%2FdateEarliestScalarValue+%3E%3D+TIMESTAMP+%222011-02-17T00%3A00%3A00%22+AND+media_common%3AdateGroupList%2F*%2FdateLatestScalarValue+%3C%3D+TIMESTAMP+%222011-03-31T23%3A59%3A59%22

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"

...

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
Code Block
controlstrue
title
HTTP/1.1 200 OK
...
<?xml version="1.0"?>
<abstract-common-list>
    <pageNum>0</pageNum>
    <pageSize>40</pageSize>
    <itemsInPage>1</itemsInPage>
    <totalItems>1</totalItems>
    <fieldsReturned>csid|uri|updatedAt|entryNumber|depositor|currentOwner</fieldsReturned>
    <list-item>
        <csid>0b72fec7-7b56-4d97-8fba</csid>
        <uri>/intakes/0b72fec7-7b56-4d97-8fba</uri>
        <updatedAt>2012-01-24T02:54:42Z</updatedAt>
        <entryNumber>EV2012.2</entryNumber>
        <depositor>urn:cspace:core.collectionspace.org:personauthorities:name(person):item:name(JohnDoe1327373674139)'John Doe'</depositor>
        <currentOwner/>
    </list-item>
</abstract-common-list>

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.

...

Note

Need to add error responses here.

...

Partial Term Matching for object/procedure/record instances

...

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

true
Code Block
controls
titlerequest for Partial term matching
GET /cspace-services/collectionobjects?pt=jone HTTP/1.1

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
Code Block
controlstrue
title
GET /cspace-services/orgauthorities/{csid}/items?pt=wildlife HTTP/1.1

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:

...

Note

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
Code Block
controlstrue
title
HTTP/1.1 200 OK
...

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.

...

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

...

as the corresponding HTTP GET methods on the associated resources:

Code Block
GET /cspace-services/personauthorities/{csid}/items?ts=Rejected HTTP/1.1


title
Code Block
controlstrue
request for all person terms that match the partial term, and have _not_ been marked as rejected
GET /cspace-services/personauthorities/{csid}/items?pt=JoeBob&ts=Rejected HTTP/1.1


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.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.

...

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

...

Code Block
GET /cspace-services/intakes/{csid}/authorityrefs/ HTTP/1.1

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

Code Block
controlstrue
titleresponse for Related authority references
HTTP/1.1 200 OK
...
Content-Type: application/xml
Content-Length: nnn
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:authority-ref-list xmlns:ns2="http://collectionspace.org/services/common/authorityref">
  <authority-ref-item>
    <sourceField>depositor</sourceField>
    <refName>urn:cspace:org.collectionspace.demo:personauthority:id(6f58aea7-defd-45a2-910c):person:id(49b382e8-b23f-4142-ad53)'James+Adams'</refName>
    <itemDisplayName>James+Adams</itemDisplayName>
    <uri>/personauthorities/6f58aea7-defd-45a2-910c/items/49b382e8-b23f-4142-ad53</uri>
  </authority-ref-item>
  ...
</ns2:authority-ref-list>

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.

...

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
Code Block
controlstrue
title
GET /cspace-services/personauthorities/urn:cspace:name(person)/items/{csid}/refObjs/ HTTP/1.1

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

controls
Code Block
true
titleresponse for object references
HTTP/1.1 200 OK
...
Content-Type: application/xml
Content-Length: nnn
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:authority-ref-doc-list xmlns:ns2="http://collectionspace.org/services/common/authorityref">
  <authority-ref-doc-item>
    <docType>Intake</docType>
    <docId>d38d5652-5e51-4a15-9ab9</docId>
    <docNumber>IN2011.1</docNumber>
    <sourceField>intakes_common:depositor</sourceField>
    <uri>/intakes/d38d5652-5e51-4a15-9ab9</uri>
  </authority-ref-doc-item>
  ...
</ns2:authority-ref-doc-list>

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.

...

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
Code Block
controlstrue
title
GET /cspace-services/personauthorities/urn:cspace:name(person)/items/{csid}/refObjs?type=procedure HTTP/1.1

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.

...

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.

title
Code Block
controlstrue
Read request for Workflow state
GET /cspace-services/collectionobjects/{csid}/workflow HTTP/1.1

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
Code Block
controlstrue
title
HTTP/1.1 200 OK
...
Content-Type: application/xml
Content-Length: nnn
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<document name="workflows">
  <ns2:workflow_common xmlns:ns2="http://collectionspace.org/services/workflow"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       <lifeCyclePolicy>default<<lifeCyclePolicy>default</lifeCyclePolicy>
        <currentLifeCycleState>deleted<<currentLifeCycleState>deleted</currentLifeCycleState>
  </ns2:workflow_common>
</document>

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.

...

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:

...

each individual service's API documentation for further details:

Code Block
PUT /cspace-services/collectionobjects/850161ed-466c-4af2-bc45/workflow/delete HTTP/1.1

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

title
Code Block
controlstrue
response to invoking 'delete' workflow state transition
HTTP/1.1 200 OK
...
Content-Type: application/xml
Content-Length: nnn
 
 
<document name="workflow">
    <ns2:workflow_common xmlns:ns2="http://collectionspace.org/services/workflow" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <lifeCyclePolicy>cs_default</lifeCyclePolicy>
    <currentLifeCycleState>deleted</currentLifeCycleState>
</ns2:workflow_common>
</document>

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
Code Block
controlstrue
title
PUT /cspace-services/collectionobjects/850161ed-466c-4af2-bc45/workflow/undelete HTTP/1.1

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
Code Block
controlstrue
title
HTTP/1.1 200 OK
...
Content-Type: application/xml
Content-Length: nnn
 
 
<document name="workflow">
    <ns2:workflow_common xmlns:ns2="http://collectionspace.org/services/workflow" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <lifeCyclePolicy>cs_default</lifeCyclePolicy>
    <currentLifeCycleState>project</currentLifeCycleState>
</ns2:workflow_common>
</document>

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 stateresponse to invoking 'lock' workflow state transition
Code Block
controlstrue
title
PUT /cspace-services/movements/ea90563a-9b34-4347-a3ab/workflow/lock HTTP/1.1
Code Block
controlstrue
title

 Code Block
HTTP/1.1 200 OK
...
Content-Type: application/xml
Content-Length: nnn
 
 
<document name="workflow">
    <ns2:workflow_common xmlns:ns2="http://collectionspace.org/services/workflow" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <lifeCyclePolicy>cs_locking</lifeCyclePolicy>
    <currentLifeCycleState>locked</currentLifeCycleState>
</ns2:workflow_common>
</document>

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:
...
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:
controls
 Code Block
true
titlerequest to Update workflow state
PUT /cspace-services/collectionobjects/850161ed-466c-4af2-bc45/workflow HTTP/1.1
Content-type: application/xml
Content-Length: nnn
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<document name="workflows">
  <ns2:workflow_common xmlns:ns2="http://collectionspace.org/services/workflow">
     <lifeCyclePolicy>default</lifeCyclePolicy>
     <currentLifeCycleState>deleted</currentLifeCycleState>
  </ns2:workflow_common>
</document>

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
 Code Block
controlstrue
title
HTTP/1.1 200 OK
...
Content-Type: application/xml
Content-Length: nnn
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<document name="workflows">
  <ns2:workflow_common xmlns:ns2="http://collectionspace.org/services/workflow"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <lifeCyclePolicy>default</lifeCyclePolicy>
     <currentLifeCycleState>deleted</currentLifeCycleState>
  </ns2:workflow_common>
</document>

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.
...
unmigrated-inline-wiki-markup
 Note
This section is an early placeholder; it needs considerable expansion and refinement.
{multi-excerpt-include:pageTitle=Common Services REST API Documentation|name=api-calls-to-retrieve-related-records|nopanel=true}
List related records via the Relations service
...
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
 Code Block
controlstrue
title
GET /cspace-services/movements?rtSbj=850161ed-466c-4af2-bc45 HTTP/1.1

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
 Code Block
controlstrue
title
GET /cspace-services/movements?rtObj=850161ed-466c-4af2-bc45 HTTP/1.1

Both of the above requests return lists of Movement records.