Page Comparison

Div

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

Place Service Home

Table of Contents

Brief Description

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

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

Assumptions

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

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

References

Vocabulary and Authority Overview
Place Service Description and Assumptions
Place Service Entity Diagrams
Place Authority Schema

...

Creates a new PlaceAuthority record. Assigns a unique, service-specified CollectionSpace ID (CSID) /wiki/spaces/collectionspace/pages/666274321 to that PlaceAuthority record. Follows standard Create model. See the documentation of the PlaceAuthority schema, below. Example:

POST /cspace-services/placeauthorities HTTP/1.1

Code Block

Read a PlaceAuthority

Reads an existing PlaceAuthority record, specified by its CollectionSpace ID (CSID) /wiki/spaces/collectionspace/pages/666274321. Follows standard Read model. See the documentation of the PlaceAuthority schema, below. Example:

GET /cspace-services/placeauthorities/{id} HTTP/1.1

Code Block

Update a PlaceAuthority

Updates an existing PlaceAuthority record, specified by its CollectionSpace ID (CSID) /wiki/spaces/collectionspace/pages/666274321. Follows standard Update model. See the documentation of the PlaceAuthority schema, below. Example:

PUT /cspace-services/placeauthorities/{id} HTTP/1.1

Code Block

Delete a PlaceAuthority

Deletes an existing PlaceAuthority record, specified by its CollectionSpace ID (CSID) /wiki/spaces/collectionspace/pages/666274321. Follows standard Delete model. Example:

DELETE /cspace-services/placeauthorities/{id} HTTP/1.1

Code Block

List PlaceAuthority instances

...

pgSz for page size
pgNum for page size

Examples:

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

Code Block

PlaceAuthority REST payload schemas

...

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

<?xml version="1.0" encoding="utf-8" standalone="yes"?> <document name="placeauthorities"> <ns2:placeauthorities_common xmlns:ns2="http://services.collectionspace.org/place"> <displayName>Default PlaceAuthority</displayName> <shortIdentifier>place</shortIdentifier> <vocabType>PlaceAuthority</vocabType> </ns2:placeauthorities_common> </document>

Code Block

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

Code Block


<?xml version="1.0" encoding="UTF-8"?>
<document name="placeauthorities">
  <ns2:collectionspace_core xmlns:ns2="http://collectionspace.org/collectionspace_core/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    ...
    <uri>/placeauthorities/afbb91ca-3988-4524-bada</uri>
    ...
  </ns2:collectionspace_core>
  <ns2:placeauthorities_common xmlns:ns2="http://collectionspace.org/services/place" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    ...
    <csid>afbb91ca-3988-4524-bada</csid>
    ...
  </ns2:placeauthorities_common>
</document>

PlaceAuthority-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|displayName|refName|shortIdentifier|vocabType</fieldsReturned> <list-item> <csid>afbb91ca-3988-4524-bada</csid> <uri>/placeauthorities/afbb91ca-3988-4524-bada</uri> <updatedAt>2012-03-29T00:51:04Z</updatedAt> <displayName>Default PlaceAuthority</displayName> <refName>urn:cspace:core.collectionspace.org:placeauthorities:name(place)'Default PlaceAuthority'</refName> <shortIdentifier>place</shortIdentifier> <vocabType/> </list-item> ... </ns2:abstract-common-list>

Code Block

Place CRUD+L services

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

...

Creates a new Place record. Assigns a unique, service-specified CollectionSpace ID (CSID) /wiki/spaces/collectionspace/pages/666274321 to that Place record. Follows standard Create model. Must See the documentation of the Place schema, below. Example:

POST /cspace-services/placeauthorities/{place-auth-id}/items HTTP/1.1

Code Block

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 Place records, which must exist before this call. The special variable ${itemCSID} will be expanded to the CSID of the newly created Place. (For Java use, please use the constant in CommonAPI.AuthorityItemCSID_REPLACE )

<?xml version="1.0" encoding="UTF-8"?> <document name="places"> <ns2:places_common xmlns:ns2="http://collectionspace.org/services/place" xmlns:ns3="http://collectionspace.org/services/jaxb"> <inAuthority>aab04036-7c9a-492d-a4d5</inAuthority> <shortIdentifier>SantaClaraCountyCA</shortIdentifier> <placeTermGroupList> <placeTermGroup> <historicalStatus>current</historicalStatus> <termDisplayName>Santa Clara County, CA</termDisplayName> </placeTermGroup> </placeTermGroupList> ... </ns2:places_common> <ns3:relations-common-list xmlns:ns3="http://collectionspace.org/services/relation" xmlns:ns2="http://collectionspace.org/services/jaxb"> <!--

Code Block

NOTE:

...

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 Place record, specified by its CollectionSpace ID (CSID) /wiki/spaces/collectionspace/pages/666274321. Follows standard Read model. See the documentation of the Place schema, below. Example:

GET /cspace-services/placeauthorities/{place-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

Update a Place in a PlaceAuthority

Updates an existing Place record, specified by its CollectionSpace ID (CSID) /wiki/spaces/collectionspace/pages/666274321. Follows standard Update model. See the documentation of the Place schema, below. Example:

Code Block
PUT /cspace-services/placeauthorities/{place-auth-id}/items/{id} HTTP/1.1

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 Place "San Jose, CA", with relations-common-list that has an entry for ${itemCSID} hasBroader "Santa Clara County" creates a relations record that references both San Jose, CA and Santa Clara County. When a PUT is made that does not have the relation for Santa Clara County, then San Jose, CA has no relations, so the relations record for San Jose, CA==>hasBroader==>Santa Clara County is deleted, but both "San Jose, CA" and "Santa Clara County" Place records remain.

...

Deletes an existing Place record, specified by its CollectionSpace ID (CSID) /wiki/spaces/collectionspace/pages/666274321. Follows standard Delete model. Example:

DELETE /cspace-services/placeauthorities/{place-auth-id}/items/{id} HTTP/1.1

Code Block

List Place instances in a PlaceAuthority

...

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

Examples:

Code Block
GET /cspace-services/placeauthorities/{place-auth-id}/items HTTP/1.1 GET /cspace-services/placeauthorities/{place-auth-id}/items?pt=foo&pgSz=10 HTTP/1.1

Place REST payload schemas

...

Info

On create, the value of inAuthority must match the identifier of the parent PlaceAuthority, 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 Place instance records, in the most recent CollectionSpace code, via this Java source code file.

Code Block


<?xml version="1.0" encoding="UTF-8"?>
<document name="places">
  <ns2:places_common xmlns:ns2="http://collectionspace.org/services/place" xmlns:ns3="http://collectionspace.org/services/jaxb">
    <inAuthority>6ca3db57-7c96-47b6-b17d</inAuthority>
    <shortIdentifier>SanJoseCA</shortIdentifier>
    <placeTermGroupList>
      <placeTermGroup>
        <historicalStatus>current</historicalStatus>
        <termDisplayName>San Jose, CA</termDisplayName>
      </placeTermGroupList>
    </placeTermGroup>
    ...
  </ns2:places_common>
</document>

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

<?xml version="1.0" encoding="UTF-8"?> <document name="places"> <ns2:collectionspace_core xmlns:ns2="http://collectionspace.org/collectionspace_core/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> ... <uri>/placeauthorities/6ca3db57-7c96-47b6-b17d/items/d286deaa-245c-4505-8b6d</uri> ... </ns2:collectionspace_core> <ns2:places_common xmlns:ns2="http://collectionspace.org/services/place" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> ... <csid>d286deaa-245c-4505-8b6d</csid> ... </ns2:places_common> ... </document>

Code Block

Place-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>8</itemsInPage> <totalItems>8</totalItems> <fieldsReturned>csid|uri|updatedAt|termType|displayName|shortIdentifier|refName|termStatus</fieldsReturned> <list-item> <csid>8efbeed8-b592-4683-869f</csid> <uri>/placeauthorities/6ca3db57-7c96-47b6-b17d/items/8efbeed8-b592-4683-869f</uri> <updatedAt>2012-03-29T01:26:46Z</updatedAt> <displayName>San Jose, CA</displayName> <shortIdentifier>SanJoseCA</shortIdentifier> <refName>urn:cspace:core.collectionspace.org:placeauthorities:name(place):item:name(SanJoseCA)'San Jose, CA'</refName> <termStatus/> </list-item> ... </ns2:abstract-common-list>

Code Block

Versions Compared

Old Version 52

New Version Current

Key

Brief Description

Assumptions

References

Read a PlaceAuthority

Update a PlaceAuthority

Delete a PlaceAuthority

List PlaceAuthority instances

PlaceAuthority REST payload schemas

PlaceAuthority-List schema

Place CRUD+L services

Update a Place in a PlaceAuthority

List Place instances in a PlaceAuthority

Place REST payload schemas

Place-List schema