Location Service REST APIs

Owned by Adaptavist ScriptRunner for Confluence Cloud
Nov 04, 2020
8 min read
Location Service Home

Brief Description

For a full description, visit the Service Description and Assumptions page.


Assumptions

For a complete list of assumptions, visit the Service Description and Assumptions page.


References

Vocabulary and Authority Overview
Location Service Description and Assumptions
Location Service Entity Diagrams
Name Authority Schema and Name Authority Schema - Limited for Release 0.4 and 0.5

REST-based API

The Location Service offers a REST-based Application Programming Interface (API) to CRUD (create, read, update, and delete) operations on individual LocationAuthority instances, and on the associated Location instances. These follow the Common model for CollectionSpace REST services.

Note that the Location instances are not directly "addressible"; they can only be accessed via the parent LocationAuthority.

LocationAuthority CRUD+L services

Create a LocationAuthority

Creates a new LocationAuthority record. Assigns a unique, service-specified CollectionSpace ID (CSID) to that LocationAuthority record. Follows standard Create model. See the documentation of the LocationAuthority schema, below. Example:

POST /cspace-services/locationauthorities HTTP/1.1
Read a LocationAuthority

Reads an existing LocationAuthority record, specified by its CollectionSpace ID (CSID). Follows standard Read model. See the documentation of the LocationAuthority schema, below. Example:

GET /cspace-services/locationauthorities/{id} HTTP/1.1
Update a LocationAuthority

Updates an existing LocationAuthority record, specified by its CollectionSpace ID (CSID). Follows standard Update model. See the documentation of the LocationAuthority schema, below. Example:

PUT /cspace-services/locationauthorities/{id} HTTP/1.1
Delete a LocationAuthority

Deletes an existing LocationAuthority record, specified by its CollectionSpace ID (CSID). Follows standard Delete model. Example:

DELETE /cspace-services/locationauthorities/{id} HTTP/1.1
List LocationAuthority instances

Lists existing LocationAuthority records, with summary information for each. Follows standard List model, with pagination support. See the documentation of the LocationAuthority-List schema, below. List supports the following common parameters for List results, pagination controls and query filters:

  • pgSz for page size
  • pgNum for page size

Examples:

GET /cspace-services/locationauthorities/ HTTP/1.1
GET /cspace-services/locationauthorities/?pgSz=10 HTTP/1.1

LocationAuthority REST payload schemas

The schemas below are abbreviated, and are thus illustrative. For a full list of the fields that may potentially be present in payloads when creating, updating, or reading individual LocationAuthority records, please see the most recent LocationAuthority schema.

LocationAuthority instance schema

Create and Update should use the following schema. The value of vocabType must be "LocationAuthority".

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<document name="locationauthorities">
  <ns2:locationauthorities_common xmlns:ns2="http://services.collectionspace.org/location">
    <displayName>Museum Internal Storage Locations</displayName>
    <vocabType>LocationAuthority</vocabType>
    ...
  </ns2:locationauthorities_common>
</document>

Read will return the above, plus additional fields (uri and csid) for access:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<document name="locationauthorities">
  <ns2:locationauthorities_common xmlns:ns2="http://services.collectionspace.org/location">
    ...
    <uri>/locationauthorities/f0cf4c50-8f8a-4df0-869a</uri>
    <csid>f0cf4c50-8f8a-4df0-869a</csid>
  </ns2:locationauthorities_common>
</document>
LocationAuthority-List schema

List (and variants) will return the following schema:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:abstract-common-list xmlns:ns2="http://collectionspace.org/services/jaxb">
  <pageNum>0</pageNum>
  <pageSize>40</pageSize>
  <itemsInPage>3</itemsInPage>
  <totalItems>3</totalItems>
  <fieldsReturned>csid|uri|updatedAt|workflowState|displayName|refName|shortIdentifier|vocabType</fieldsReturned>
  <list-item>
    <displayName>Museum Internal Storage Locations</displayName>
    <refName>urn:cspace:core.collectionspace.org:locationauthorities:name(MuseumInternal)'Museum Internal Storage Locations'</refName>
    <vocabType>LocationAuthority</vocabType>
    <uri>/locationauthorities/f0cf4c50-8f8a-4df0-869a</uri>
    <csid>f0cf4c50-8f8a-4df0-869a</csid>
  </list_item>
  ...
</ns2:abstract-common-list>

Location CRUD+L services

Location instances are only accessible via the owning LocationAuthority. The sub-resource is accessed with "items" (for consistency across all vocabulary-like services). In the examples below, the {location-auth-id} parameter represents the CSID value of an existing LocationAuthority instance.

Create a Location in a LocationAuthority

Creates a new Location record. Assigns a unique, service-specified CollectionSpace ID (CSID) to that Location record. Follows standard Create model. Must See the documentation of the Location schema, below. Example:

POST /cspace-services/locationauthorities/{location-auth-id}/items HTTP/1.1

You may also POST a part called

<ns3:relations-common-list>

and any new relations there will be created. For example, this POST will add a relationship. Note that you must know beforehand the CSIDs of related terms. These are the CSIDs of two other Person records, which must exist before this call. The special variable ${itemCSID} will be expanded to the CSID of the newly created Person. (For Java use, please use the constant in CommonAPI.AuthorityItemCSID_REPLACE )

<?xml version="1.0" encoding="UTF-8"?>
<document name="locations">
  <ns2:locations_common xmlns:ns2="http://collectionspace.org/services/location" xmlns:ns3="http://collectionspace.org/services/jaxb">
    <inAuthority>42a0f410-ce34-4696-b594</inAuthority>
    <locTermGroupList>
        <locTermGroup>
            <termDisplayName>Shelf 1</termDisplayName>
            <termStatus>provisional</termStatus>
        </locTermGroup>
    </locTermGroupList>
    ...
  </ns2:locations_common>

  <ns3:relations-common-list xmlns:ns3="http://collectionspace.org/services/relation" xmlns:ns2="http://collectionspace.org/services/jaxb">
    <relation-list-item>
                <predicate>hasBroader</predicate>
                <subject>
                  <csid>${itemCSID}</csid>
                  <documentType>Location</documentType>
                </subject>
                <object>
                  <csid>2a5f119a-acd0-4b89-a535</csid>
                  <uri>/cspace-services/locationauthorities/urn:cspace:name(CSPACE3739LocationAuthority)/items/2a5f119a-acd0-4b89-a535</uri>
                  <documentType>Location</documentType>
                </object>
        </relation-list-item>
        <relation-list-item>
                <predicate>hasBroader</predicate>
                <subject>
                  <csid>b11d978a-2a30-463b-9782</csid>
                  <uri>/cspace-services/locationauthorities/urn:cspace:name(CSPACE3739LocationAuthority)/items/b11d978a-2a30-463b-9782</uri>
                  <documentType>Location</documentType>
                </subject>
                <object>
                  <csid>${itemCSID}</csid>
                  <documentType>Location</documentType>
                </object>
        </relation-list-item>
        <relation-list-item>
                <predicate>hasBroader</predicate>
                <subject>
                  <uri>/cspace-services/locationauthorities/urn:cspace:name(CSPACE3739LocationAuthority)/items/923b2239-ccb8-493a-beb1</uri>
                  <csid>923b2239-ccb8-493a-beb1</csid>
                  <documentType>Location</documentType>
                </subject>
                <object>
                  <csid>${itemCSID}</csid>
                  <documentType>Location</documentType>
                </object>
        </relation-list-item>
        <relation-list-item>
                <predicate>hasBroader</predicate>
                <subject>
                  <uri>/cspace-services/locationauthorities/urn:cspace:name(CSPACE3739LocationAuthority)/items/d3c11cc2-ef65-4994-b800</uri>
                  <csid>d3c11cc2-ef65-4994-b800</csid>
                  <documentType>Location</documentType>
                </subject>
                <object>
                  <csid>${itemCSID}</csid>
                  <documentType>Location</documentType>
                </object>
        </relation-list-item>
  </ns3:relations-common-list>
</document>

NOTE: if you wish to delete related items,
simply send relations-common-list as an empty element.
This is shown in a comment here:
http://wiki.collectionspace.org/display/collectionspace/Person+Service+REST+APIs?focusedCommentId=72220749&#comment-72220749

Read a Location in a LocationAuthority

Reads an existing Location record, specified by its CollectionSpace ID (CSID). Follows standard Read model. See the documentation of the Location schema, below. Example:

GET /cspace-services/locationauthorities/{location-auth-id}/items/{id} HTTP/1.1

There are additional query parameters to get the relations for this item.
Query Parameters are defined and explained here, with examples: Authority REST API for Hierarchies

Update a Location in a LocationAuthority

Updates an existing Location record, specified by its CollectionSpace ID (CSID). Follows standard Update model. See the documentation of the Location schema, below. Example:

PUT /cspace-services/locationauthorities/{location-auth-id}/items/{id} HTTP/1.1

You may also PUT a part called

<ns3:relations-common-list>

and any new relations there will be created. Relations to the updated item which are missing from the relations list in the PUT will be deleted from persistence. No target records are deleted, just the relations records that point to target records. e.g. POST to authority with Location "Shelf_33", with relations-common-list that has an entry for ${itemCSID} hasBroader "Cabinet_101" creates a relations record that references both Cabinet_101 and Shelf_33. When a PUT is made that does not have the relation for Cabinet_101, then Shelf_33 has no relations, so the relations record for Shelf_33==>hasBroader==>Cabinet_101 is deleted, but both "Shelf_33" and "Cabinet_101" Person records remain.

Delete a Location in a LocationAuthority

Deletes an existing Location record, specified by its CollectionSpace ID (CSID). Follows standard Delete model. Example:

DELETE /cspace-services/locationauthorities/{location-auth-id}/items/{id} HTTP/1.1
List Location instances in a LocationAuthority

Lists existing Location records, with summary information for each. Follows standard List model. See the documentation of the Location-List schema, below. List supports the following common parameters for List results, pagination controls and query filters:

  • pgSz for page size
  • pgNum for page size
  • pt for partial-term matching, to support term completion.

Examples:

GET /cspace-services/locationauthorities/{location-auth-id}/items/ HTTP/1.1
GET /cspace-services/locationauthorities/{location-auth-id}/items/?pt=foo&pgSz=10 HTTP/1.1

Location REST payload schemas

The schemas below are abbreviated, and are thus illustrative. For a full list of the fields that may potentially be present in payloads when creating, updating, or reading individual Location records, please see the most recent Location schema (i.e. for an individual Location term within a LocationAuthority or vocabulary).

Location instance schema

Create and Update should use the following schema.

On create, the value of inAuthority must match the identifier of the parent LocationAuthority, and will not be modified once the instance is created.

You can view the full set of validation constraints on the data you submit when creating or updating Location instance records, in the most recent CollectionSpace code, via this Java source code file.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<document name="locations">
    <ns2:locations_common xmlns:ns2="http://collectionspace.org/services/location" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <shortIdentifier>Shelf11343241264146</shortIdentifier>
    <inAuthority>24f28db2-d477-4a62-8670</inAuthority>
    <locTermGroupList>
        <locTermGroup>
            <termPrefForLang>true</termPrefForLang>
            <termDisplayName>Shelf 1</termDisplayName>
            <termStatus>provisional</termStatus>
        </locTermGroup>
    </locTermGroupList>
    <securityNote>Kind of safe</securityNote>
    <locationType>urn:cspace:core.collectionspace.org:vocabularies:name(locationtype):item:name(shelf)'Shelf'</locationType>
    <conditionGroupList>
        <conditionGroup>
            <conditionNote>Basically clean</conditionNote>
            <conditionNoteDate>2012-07-05T00:00:00Z</conditionNoteDate>
        </conditionGroup>
    </conditionGroupList>
</ns2:locations_common>

Read will return the above, plus additional fields (uri and csid) for access:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:locations_common xmlns:ns2="http://services.collectionspace.org/location">
...
<uri>/locationauthorities/f0cf4c50-8f8a-4df0-869a/items/a256aed3-0b0a-44e6-84b0</uri>
<csid>a256aed3-0b0a-44e6-84b0</csid>
</ns2:locations_common>
Location-List schema

List (and variants) will return a schema similar to the following example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:abstract-common-list xmlns:ns2="http://collectionspace.org/services/jaxb">
<pageNum>0</pageNum>
<pageSize>40</pageSize>
<itemsInPage>1</itemsInPage>
<totalItems>1</totalItems>
<fieldsReturned>csid|uri|updatedAt|workflowState|termDisplayName|shortIdentifier|refName|termStatus</fieldsReturned>
<list-item>
    <csid>9e8b572d-8a8b-4b63-91a5</csid>
    <uri>/locationauthorities/24f28db2-d477-4a62-8670/items/9e8b572d-8a8b-4b63-91a5</uri>
    <updatedAt>2012-07-25T18:34:24Z</updatedAt>
    <workflowState>project</workflowState>
    <termDisplayName>Shelf 1</termDisplayName>
    <shortIdentifier>Shelf11343241264146</shortIdentifier>
    <refName>urn:cspace:core.collectionspace.org:locationauthorities:name(location):item:name(Shelf11343241264146)'Shelf 1'</refName>
    <termStatus>provisional</termStatus>
</list-item>
</ns2:abstract-common-list>