Vocabulary Service REST APIs - Release v0.1

Owned by Adaptavist ScriptRunner for Confluence Cloud
Oct 28, 2020
4 min read
Vocabulary Service Home

Brief Description

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

Assumptions

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

References

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

REST-based API

The Vocabulary Service offers a REST-based Application Programming Interface (API) to CRUD (create, read, update, and delete) operations on individual Vocabulary instances, and on the associated VocabularyItem instances. These follow the Common model for CollectionSpace REST services.

Note that the VocabularyItem instances are not directly "addressible"; they can only be accessed via the parent Vocabulary.

Vocabulary CRUD+L services

Create a Vocabulary

Creates a new Vocabulary record. Assigns a unique, service-specified CollectionSpace ID (CSID) to that Vocabulary record. Follows standard Create model. See the documentation of the Vocabulary schema, below. Example:

POST /cspace-services/vocabularies HTTP/1.1

Read a Vocabulary

Reads an existing Vocabulary record, specified by its CollectionSpace ID (CSID). Follows standard Read model. See the documentation of the Vocabulary schema, below.

General form:

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

Example, reading an existing record with a CSID of e450e8e8-9f12-49f3-aba4-43b7c46344a2:

GET /cspace-services/vocabularies/e450e8e8-9f12-49f3-aba4-43b7c46344a2 HTTP/1.1

An alternate form reads an existing Vocabulary record, specified by its short identifier, which matches the value of the shortIdentifier field in the record. Otherwise follows standard Read model. See the documentation of the Vocabulary schema, below.

General form:

GET /cspace-services/vocabularies/urn:cspace:name({id}) HTTP/1.1

Example, reading an existing record with a shortIdentifier value of myDefaultVocabulary:

GET /cspace-services/vocabularies/urn:cspace:name(myDefaultVocabulary) HTTP/1.1
Update a Vocabulary

Updates an existing Vocabulary record, specified by its CollectionSpace ID (CSID). Follows standard Update model. See the documentation of the Vocabulary schema, below. Example:

PUT /cspace-services/vocabularies/{id} HTTP/1.1
Delete a Vocabulary

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

DELETE /cspace-services/vocabularies/{id} HTTP/1.1
List Vocabulary instances

Lists existing Vocabulary records, with summary information for each. Follows standard List model. See the documentation of the Vocabulary-List schema, below.

Examples:

GET /cspace-services/vocabularies HTTP/1.1

List supports query parameters for customizing list results, such as pagination controls, query filters, and sorting options. For example:

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

List also supports query parameters for searching for matching records, including keyword search. For example:

GET /cspace-services/vocabularies?kw=foo&pgSz=10 HTTP/1.1

Vocabulary REST payload schemas

Vocabulary instance schema

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

Validation constraints: Values for shortIdentifier must be non-null and may only include word characters ("a-zA-Z0-9_"), or call will return 400 Bad Request.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:vocabularies-common xmlns:ns2="http://services.collectionspace.org/vocabulary">
  <displayName>Gender Values</displayName>
  <shortIdentifier>gender</shortIdentifier>
  <refName>urn:cspace:org.collectionspace.demo:vocabulary:name(gender)'Gender Values'</refName>
  <vocabType>enum</vocabType>
</ns2:vocabularies-common>

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

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:vocabularies-common xmlns:ns2="http://services.collectionspace.org/vocabulary">
  ...
  <uri>/vocabularies/f0cf4c50-8f8a-4df0-869a</uri>
  <csid>f0cf4c50-8f8a-4df0-869a</csid>
</ns2:vocabularies-common>
Vocabulary-List schema

List (and variants) will return the following schema. Note the standard pagination support.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:vocabularies-common-list xmlns:ns2="http://services.collectionspace.org/vocabulary">
  <pageNum>0</pageNum>
  <pageSize>40</pageSize>
  <totalItems>3</totalItems>
  <list-item>
    <displayName>Gender Values</displayName>
    <refName>urn:cspace:org.collectionspace.demo:vocabulary:name(gender)'Gender Values'</refName>
    <vocabType>enum</vocabType>
    <uri>/vocabularies/f0cf4c50-8f8a-4df0-869a</uri>
    <csid>f0cf4c50-8f8a-4df0-869a</csid>
  </list-item>
  ...
</ns2:vocabularies-common-list>

VocabularyItem CRUD+L services

VocabularyItem instances are only accessible via the owning Vocabulary. The sub-resource is accessed with "items" (this is consistent across all vocabulary-like services). In the examples below, the {vocabulary-id} parameter represents an identifier (such as a CSID value) of an existing Vocabulary instance.

Create a VocabularyItem in a Vocabulary

Creates a new VocabularyItem record. Assigns a unique, service-specified CollectionSpace ID (CSID) to that VocabularyItem record. Follows standard Create model. See the documentation of the VocabularyItem schema, below. Example:

POST /cspace-services/vocabularies/{vocabulary-id}/items HTTP/1.1
Read a VocabularyItem in a Vocabulary

Reads an existing VocabularyItem record, specified by its CollectionSpace ID (CSID). Follows standard Read model. See the documentation of the VocabularyItem schema, below. Example:

GET /cspace-services/vocabularies/{vocabulary-id}/items/{id} HTTP/1.1
Update a VocabularyItem in a Vocabulary

Updates an existing VocabularyItem record, specified by its CollectionSpace ID (CSID). Follows standard Update model. See the documentation of the VocabularyItem schema, below. Example:

PUT /cspace-services/vocabularies/{vocabulary-id}/items/{id} HTTP/1.1
Delete a VocabularyItem in a Vocabulary

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

DELETE /cspace-services/vocabularies/{vocabulary-id}/items/{id} HTTP/1.1
List VocabularyItem instances in a Vocabulary

Lists existing VocabularyItem records, with summary information for each. Follows standard List model. The vocabulary may be specified either using the CSID or the shortIdentifier, using the syntax described for vocabulary read, described above. See the documentation of the VocabularyItem-List schema, below.

Examples:

GET /cspace-services/vocabularies/{vocabulary-id}/items HTTP/1.1

List supports query parameters for customizing list results, such as pagination controls, query filters, and sorting options. For example:

GET /cspace-services/vocabularies/{vocabulary-id}/items?pgSz=10 HTTP/1.1

List also supports query parameters for searching for matching records, including:

  • keyword search
  • partial term matching search, for term completion
  • term status filtering, to exclude (filter out) records matching one or more statuses

For example:

GET /cspace-services/vocabularies/{vocabulary-id}/items?pt=foo&pgSz=10 HTTP/1.1

VocabularyItem REST payload schemas

VocabularyItem instance schema

Create and Update should use the following schema. The value of inVocabulary must match the parent vocabulary, and must not be modified once the instance is created.

Validation constraints: On create and update, displayName must be non-null and at least 2 characters long, or call will return 400 Bad Request. Values for shortIdentifier must be non-null and may only include word characters ("a-zA-Z0-9_").

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
  <ns2:vocabularyitems-common xmlns:ns2="http://services.collectionspace.org/vocabulary">
  <inVocabulary>f0cf4c50-8f8a-4df0-869a</inVocabulary>
  <displayName>Male Gender</displayName>
  <shortIdentifier>male</shortIdentifier>
  <refName>
    urn:cspace:org.collectionspace.demo:vocabulary:name(gender):item:name(male)'Male Gender'
  </refName>
</ns2:vocabularyitems-common>

Note: You might need to wrap some of the payload in <document> tags, e.g.,

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<document name="vocabularyitems">
    <ns2:vocabularyitems_common xmlns:ns2="http://collectionspace.org/services/vocabulary" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <inAuthority>42f984c3-4e24-4702-8825</inAuthority>
        <termStatus>active</termStatus>
        <displayName>box</displayName>
        <shortIdentifier>box</shortIdentifier>
        <refName>urn:cspace:ucjeps.cspace.berkeley.edu:vocabularies:name(locationtype):item:name(box)'box'</refName>
    </ns2:vocabularyitems_common>
</document>

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

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:vocabularyitems-common xmlns:ns2="http://services.collectionspace.org/vocabulary">
...
<uri>/vocabularies/f0cf4c50-8f8a-4df0-869a/items/a256aed3-0b0a-44e6-84b0</uri>
<csid>a256aed3-0b0a-44e6-84b0</csid>
</ns2:vocabularyitems-common>
VocabularyItem-List schema

List (and variants) will return the following schema. Note the standard pagination support.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
  <ns2:vocabularyitems-common-list xmlns:ns2="http://services.collectionspace.org/vocabulary">
  <pageNum>0</pageNum>
  <pageSize>40</pageSize>
  <totalItems>3</totalItems>
  <vocabulary-list-item>
    <displayName>male</displayName>
    <refName>
     urn:cspace:org.collectionspace.demo:vocabulary:name(Gender):item:name(male)'Male Gender'
    </refName>
    <uri>/vocabularies/f0cf4c50-8f8a-4df0-869a/items/a256aed3-0b0a-44e6-84b0</uri>
    <csid>a256aed3-0b0a-44e6-84b0</csid>
  </vocabulary-list-item>
  ...
</ns2:vocabularyitems-common-list>