Brief Description

Assumptions

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
• LocationAuthority REST payload schemas
• Location CRUD+L services
• Location REST payload schemas

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:

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:

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:

Delete a LocationAuthority

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

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:

LocationAuthority REST payload schemas

LocationAuthority instance schema

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

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

LocationAuthority-List schema

List (and variants) will return the following schema:

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:

You may also POST a part called

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 )

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:

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:

You may also PUT a part called

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:

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:

Location REST payload schemas

Location instance schema

Create and Update should use the following schema.

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

Location-List schema

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