Versions Compared

Old Version 3

changes.mady.by.user Jesse Martinez

Saved on

compared with

New Version 4

changes.mady.by.user Jesse Martinez

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin
Div
stylefont-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:

POST /cspace-services/locationauthorities HTTP/1.1
Code Block
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

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

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

 Code Block
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 
<ns3:relations-common-list>
 Code Block
 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>

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

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

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

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

 Code Block
You may also PUT a part called 
<ns3:relations-common-list>
 Code Block
 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:
DELETE /cspace-services/locationauthorities/{location-auth-id}/items/{id} HTTP/1.1

 Code Block
List Location instances in a LocationAuthority
...
  • 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

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

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


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

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

 Code Block