Authority REST API for Hierarchies

Owned by Jesse Martinez
Sept 11, 2012
2 min read

Definitions

Authorities that support hierarchies of terms behave differently than other Authorities.

Currently, the following Authorities provide this behavior:

LocationAuthority (/locationauthorities)
PersonAuthority (/personauthorities)
OrgAuthority (/orgauthorities)
TaxonAuthority (/taxonomyauthorities)
VocabularyAuthority (/vocabularies) TODO: Vocabularies are supposed to be flat? But they inherit from the same base class...)

Other services may be found here: RESTful Rollup

For all queries, the target of the URI is called the "item". For example with this URL, 

http://collectionspace.org:8180/cspace-services/locationauthorities/e14c5cee-5cbd-4b26-8b69/items/79eba6b9-03e6-46ad-ac44?showRelations=true

the URI is considered to be /locationauthorities/e14c5cee-5cbd-4b26-8b69/items/79eba6b9-03e6-46ad-ac44 and the item is the document whose CSID is 79eba6b9-03e6-46ad-ac44, and the Authority has a CSID of e14c5cee-5cbd-4b26-8b69.

Another item that is related to this item using the hierarchy capabilities of a POST or PUT to one of the above Authorities is either a parent, sibling, or child.

  • A parent has a Relation that says there is a subject of the child's CSID, an object of the parent's CSID, and a predicated of RelationshipType.HAS_BROADER or "hasBroader".
  • A child has a Relation that says the subject is the child's CSID, a predicated of "hasBroader", and an object of the current item's CSID.
  • A sibling is an item that has a Relation that says the object is the same CSID as the current item's parent's CSID.

Query Parameters

These authorities accept the following query parameters to affect what they return:

ParameterName

ParameterValue

Meaning

showRelations

true or false

if showRelations=true is sent, the response will include a part called relations-common-list which will contain the item, and any parents. There is a rule that says an item may only have one parent.

showAllRelations

true or false

if showAllRelations=true is sent, the response will include a relations-common-list part that contains the item, the parent, and any siblings.

showSiblings

true or false

if showSiblings=true is sent, the relations-common-list will include the siblings, and neither the item nor the parent.

These parameters are mutually exclusive. They may not be combined in the URL.

If no query parameter is sent, the relations-common-list part will not be returned.

Examples

http://localhost:8180/cspace-services/locationauthorities/e14c5cee-5cbd-4b26-8b69/items/79eba6b9-03e6-46ad-ac44?showRelations=true
http://localhost:8180/cspace-services/locationauthorities/e14c5cee-5cbd-4b26-8b69/items/79eba6b9-03e6-46ad-ac44?showSiblings=true
http://localhost:8180/cspace-services/locationauthorities/e14c5cee-5cbd-4b26-8b69/items/79eba6b9-03e6-46ad-ac44?showAllRelations=true

These examples and many more, along with their resulting payloads, may be seen here: http://wiki.collectionspace.org/download/attachments/72548501/location-hierarchy-rest-api.html
To see a payload on that page, click on the hyperlink titled RESPONSE.

Java API Constants and Maven Coordinates

If you will be accessing these query parameters programmatically, you are encouraged to you the symbolic query parameter names found here:

org.collectionspace.services.common.api.CommonAPI.showRelations_QP
org.collectionspace.services.common.api.CommonAPI.showSiblings_QP
org.collectionspace.services.common.api.CommonAPI.showAllRelations_QP

The string value of these variables is subject to change, but will be up-to-date in the services common-api module, which has maven coordinates:

    <groupId>org.collectionspace.services</groupId>
    <artifactId>org.collectionspace.services.common-api</artifactId>
    <name>services.common-api</name>

See Also

Relationship Service RESTful APIs