Page Comparison

Div

style	font-weight:bold;font-size:1.2em;

Location Service Home

Brief Description

Wiki Markup
{multi-excerpt-include:Location Service Description and Assumptions\|name=brief-description\|nopanel=true}

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

...

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:

Code Block
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:

Code Block
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:

Code Block
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:

Code Block
DELETE /cspace-services/locationauthorities/{id} HTTP/1.1

List LocationAuthority instances

...

pgSz for page size
pgNum for page size

Examples:

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

LocationAuthority REST payload schemas

...

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

Code Block


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

Code Block


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

Code Block


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

...

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:

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

You may also POST a part called

Code Block
<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 )

Code Block


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

...

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

Code Block
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

...

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

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

You may also PUT a part called

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

...

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

Code Block
DELETE /cspace-services/locationauthorities/{location-auth-id}/items/{id} HTTP/1.1

List Location instances in a LocationAuthority

...

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

Examples:

Code Block
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

...

Info

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.

Code Block


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

Code Block

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

Code Block


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

Versions Compared

Old Version 4

New Version Current

Key

Brief Description

Read a LocationAuthority

Update a LocationAuthority

Delete a LocationAuthority

List LocationAuthority instances

LocationAuthority REST payload schemas

LocationAuthority-List schema

Location CRUD+L services

List Location instances in a LocationAuthority

Location REST payload schemas

Location-List schema