Authority REST API for Hierarchies
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>