Versions Compared

Old Version 27

changes.mady.by.user Chris Hoffman

Saved on

compared with

New Version 28

changes.mady.by.user Chris Hoffman

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 4.0
Wiki Markup
{div:style=font-weight:bold;font-size:1.2em;}[Vocabulary Service Home]
{div}

h3.

Brief

...

Description

Wiki Markup
{multi-excerpt-include:Vocabulary 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:Vocabulary 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
 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:
 Code Block
POST /cspace-services/vocabularies HTTP/1.1
{code}

{anchor:read}

h5. Read a Vocabulary

Reads an existing Vocabulary record, specified by its [CollectionSpace ID (CSID)|CollectionSpace ID (CSID)]. Follows standard [Read|collectionspace:Common Services REST API documentation#Read an object/procedure/record instance] model. See the documentation of the Vocabulary schema, below.

General form:
{code}
 Anchor
read
read
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:
 Code Block
GET /cspace-services/vocabularies/{id} HTTP/1.1
{code}


Example, 
...
 reading 
...
 an 
...
 existing 
...
 record 
...
 with 
...
 a 
...
 CSID 
...
 of 
...
 e450e8e8-9f12-49f3-aba4-43b7c46344a2:
...
}
 Code Block
GET /cspace-services/vocabularies/e450e8e8-9f12-49f3-aba4-43b7c46344a2 HTTP/1.1
{code}


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:
 Code Block
GET /cspace-services/vocabularies/urn:cspace:name({id}) HTTP/1.1
{code}


Example, 
...
 reading 
...
 an 
...
 existing 
...
 record 
...
 with 
...
 a 
...
 shortIdentifier value of myDefaultVocabulary:
 Code Block
GET /cspace-services/vocabularies/urn:cspace:name(myDefaultVocabulary) HTTP/1.1
{code}

h5. Update a Vocabulary

Updates an existing Vocabulary record, specified by its [CollectionSpace ID (CSID)|CollectionSpace ID (CSID)]. Follows standard [Update|collectionspace:Common Services REST API documentation#Update an object/procedure/record instance] model. See the documentation of the Vocabulary schema, below. Example:
{code}
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:
 Code Block
PUT /cspace-services/vocabularies/{id} HTTP/1.1
{code}

h5. Delete a Vocabulary

Deletes an existing Vocabulary record, specified by its [CollectionSpace ID (CSID)|CollectionSpace ID (CSID)]. Follows standard [Delete|collectionspace:Common Services REST API documentation#Delete an object/procedure/record instance] model. Example:
{code}
Delete a Vocabulary
Deletes an existing Vocabulary record, specified by its CollectionSpace ID (CSID). Follows standard Delete model. Example:
 Code Block
DELETE /cspace-services/vocabularies/{id} HTTP/1.1
{code}

h5. List Vocabulary instances

Lists existing Vocabulary records, with summary information for each. Follows standard [List|collectionspace:Common Services REST API documentation#List All object/procedure/record instance] model. See the documentation of the Vocabulary-List schema, below.

Examples:
{code}/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:
 Code Block
GET /cspace-services/vocabularies HTTP/1.1
{code}


List 
...
 supports 
...
 query 
...
 parameters 
...
 for 
...
 customizing 
...
 list 
...
 results, 
...
 such 
...
 as 
...
pagination 
...
 controls, 
...
 query 
...
 filters, 
...
 and 
...
 sorting 
...
 options
...
. 
...
 For 
...
 example:
...
}
 Code Block
GET /cspace-services/vocabularies?pgSz=10 HTTP/1.1
{code}


List 
...
 also 
...
 supports 
...
 query 
...
 parameters 
...
 for 
...
searching 
...
 for 
...
 matching 
...
 records
...
, 
...
 including 
...
 keyword 
...
 search. 
...
 For 
...
 example:
...
}
 Code Block
GET /cspace-services/vocabularies?kw=foo&pgSz=10 HTTP/1.1
{code}

h3. Vocabulary REST payload schemas

h5. 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 
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.
...
}
 Code Block
<?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>
{code}
Read 
...
 will 
...
 return 
...
 the 
...
 above, 
...
 plus 
...
 additional 
...
 fields 
...
 (
...
uri
...
 and 
...
csid
...
) 
...
 for 
...
 access:
...
}
 Code Block
<?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>
{code}

h5. 

Vocabulary-List 
...
 schema
...
List 
...
 (and 
...
 variants) 
...
 will 
...
 return 
...
 the 
...
 following 
...
 schema. 
...
 Note 
...
 the 
...
 standard 
...
 pagination 
...
 support.
...
}
 Code Block
<?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>
  <vocabulary-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>
  </vocabulary-list-item>
  ...
</ns2:vocabularies-common-list>
{code}

h3. VocabularyItem 
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:
...
}
 Code Block
POST /cspace-services/vocabularies/{vocabulary-id}/items HTTP/1.1
{code}

h5.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:
 Code Block
GET /cspace-services/vocabularies/{vocabulary-id}/items/{id} HTTP/1.1
{code}

h5. Update a VocabularyItem in a Vocabulary

Updates an existing VocabularyItem record, specified by its [CollectionSpace ID (CSID)|CollectionSpace ID (CSID)]. Follows standard [Update|collectionspace:Common Services REST API documentation#Update an object/procedure/record instance] model. See the documentation of the VocabularyItem schema, below. Example:
{code}
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:
 Code Block
PUT /cspace-services/vocabularies/{vocabulary-id}/items/{id} HTTP/1.1
{code}

h5. Delete a VocabularyItem in a Vocabulary

Deletes an existing VocabularyItem record, specified by its [CollectionSpace ID (CSID)|CollectionSpace ID (CSID)]. Follows standard [Delete|collectionspace:Common Services REST API documentation#Delete an object/procedure/record instance] model. Example:
{code}

Delete a VocabularyItem in a Vocabulary
Deletes an existing VocabularyItem record, specified by its CollectionSpace ID (CSID). Follows standard Delete model. Example:
 Code Block
DELETE /cspace-services/vocabularies/{vocabulary-id}/items/{id} HTTP/1.1
{code}

h5. List VocabularyItem instances in a Vocabulary

Lists existing VocabularyItem records, with summary information for each. Follows standard [List|collectionspace:Common Services REST API documentation#List All object/procedure/record instance] 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:
{code}
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:
 Code Block
GET /cspace-services/vocabularies/{vocabulary-id}/items HTTP/1.1
{code}


List 
...
 supports 
...
 query 
...
 parameters 
...
 for 
...
 customizing 
...
 list 
...
 results, 
...
 such 
...
 as 
...
pagination 
...
 controls, 
...
 query 
...
 filters, 
...
 and 
...
 sorting 
...
 options
...
. 
...
 For 
...
 example:
...
}
 Code Block
GET /cspace-services/vocabularies/{vocabulary-id}/items?pgSz=10 HTTP/1.1
{code}


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:
 Code Block
GET /cspace-services/vocabularies/{vocabulary-id}/items?pt=foo&pgSz=10 HTTP/1.1
{code}

h3. VocabularyItem REST payload schemas

h5. 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 
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_").
...
}
 Code Block
<?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>
{code}
Note: 
...
 You 
...
 might 
...
 need 
...
 to 
...
 wrap 
...
 some 
...
 of 
...
 the 
...
 payload 
...
 in 
...
 <document> 
...
 tags, 
...
 e.g.,
...
}
 Code Block
<?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>{code}

Read 
...
 will 
...
 return 
...
 the 
...
 above, 
...
 plus 
...
 additional 
...
 fields 
...
 (
...
uri
...
 and 
...
csid
...
) 
...
 for 
...
 access:
...
}
 Code Block
<?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>
{code}

h5. 
VocabularyItem-List 
...
 schema
...
List 
...
 (and 
...
 variants) 
...
 will 
...
 return 
...
 the 
...
 following 
...
 schema. 
...
 Note 
...
 the 
...
 standard 
...
 pagination 
...
 support.
...
}
 Code Block
<?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>
{code}