Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 39 Next »

Citation Service Home

Brief Description

Unknown macro: {multi-excerpt-include}
For a full description, visit the Service Description and Assumptions page.

Assumptions

Unknown macro: {multi-excerpt-include}
For a complete list of assumptions, visit the Service Description and Assumptions page.

References

Vocabulary and Authority Overview
Citation Service Description and Assumptions
Citation Service Entity Diagrams
CitationAuthority Schema, CitationAuthority Schema and Mockup - UCB Version

REST-based API

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

Note that the Citation instances are not directly "addressable"; they can only be accessed via the parent CitationAuthority.

CitationAuthority CRUD+L services

Create a CitationAuthority

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

POST /cspace-services/citationauthorities HTTP/1.1
Read a CitationAuthority

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

GET /cspace-services/citationauthorities/{id} HTTP/1.1
Update a CitationAuthority

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

PUT /cspace-services/citationauthorities/{id} HTTP/1.1
Delete a CitationAuthority

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

DELETE /cspace-services/citationauthorities/{id} HTTP/1.1
List CitationAuthority instances

Lists existing CitationAuthority records, with summary information for each. Follows standard List model, with pagination support. See the documentation of the CitationAuthority-List schema, below. List supports the following common parameters for List results, pagination controls and query filters:

  • pgSz for page size
  • pgNum for page number

Examples:

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

CitationAuthority REST payload schemas

The schemas below are abbreviated, and are thus illustrative.  For a full list of the fields that may potentially be present in payloads when creating, updating, or reading individual CitationAuthority records, please see the most recent CitationAuthority schema.

CitationAuthority instance schema

Create and Update should use the following schema.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<document name="citations">
  <ns2:citations_common xmlns:ns2="http://services.collectionspace.org/citation">
     <citationTermGroupList>
        <citationTermGroup>
           <displayName>Quis custodiet ipsos custodes</displayName>
        </citationTermGroup>
     </citationTermGroupList>
    ...
  </ns2:citations_common>
</document>

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

<?xml version="1.0" encoding="UTF-8"?>
<document name="citations">
  <ns2:collectionspace_core xmlns:ns2="http://collectionspace.org/collectionspace_core/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     ...
     <uri>/citationauthorities/afbb91ca-3988-4524-bada</uri>
     ...
  </ns2:collectionspace_core>
  <ns2:citations_common xmlns:ns2="http://collectionspace.org/services/citation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     ...
     <csid>afbb91ca-3988-4524-bada</csid>
     ...
  </ns2:citations_common>
</document>
CitationAuthority-List schema

List (and variants) will return the following schema:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:abstract-common-list xmlns:ns2="http://collectionspace.org/services/jaxb">
  <pageNum>0</pageNum>
  <pageSize>40</pageSize>
  <itemsInPage>3</itemsInPage>
  <totalItems>3</totalItems>
  <fieldsReturned>csid|uri|updatedAt|termDisplayName|refName|shortIdentifier</fieldsReturned>
  <list-item>
    <csid>afbb91ca-3988-4524-bada</csid>
    <uri>/citationauthorities/afbb91ca-3988-4524-bada/items/c673a8a9-6559-4c94-a86d</uri>
    <updatedAt>2012-03-29T00:51:04Z</updatedAt>
    <refName>urn:cspace:core.collectionspace.org:citationauthorities:name(Quiscustodietipsoscustodes1367585080203)'Quis custodiet ipsos custodes'
    <termDisplayName>Quis custodiet ipsos custodes</termDisplayName>
    <shortIdentifier>Quiscustodietipsoscustodes1367585080203</shortIdentifier>
  </list-item>
   ...
</ns2:abstract-common-list>

Citation CRUD+L services

Citation instances are only accessible via the owning CitationAuthority. The sub-resource is accessed with "items" (for consistency across all vocabulary-like services). In the examples below, the {citation_auth_id} parameter represents the CSID value of an existing CitationAuthority instance.

Create a Citation in a CitationAuthority

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

POST /cspace-services/citationauthorities/{citation-auth-id}/items HTTP/1.1

You may also POST a part called

<ns3:relations-common-list>

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 Citation records, which must exist before this call.  The special variable ${itemCSID} will be expanded to the CSID of the newly created Citation. (For Java use, please use the constant in CommonAPI.AuthorityItemCSID_REPLACE )

<document name="citations">
   <ns2:citations_common xmlns:ns2="http://collectionspace.org/services/citation" xmlns:ns3="http://collectionspace.org/services/jaxb">
       <inAuthority>6ca3db57-7c96-47b6-b17d</inAuthority>
       <shortIdentifier>Quiscustodietipsoscustodes1367585080203</shortIdentifier>
       <citationTermGroupList>
             <citationTermGroup>
                  <displayName>Quis custodiet ipsos custodes</displayName>
             </citationTermGroup>
       </citationTermGroupList>
       ...
   </ns2:citations_common>

   <ns3:relations-common-list xmlns:ns3="http://collectionspace.org/services/relation" xmlns:ns2="http://collectionspace.org/services/jaxb">
       <relation-list-item>
           <predicate>hasBroader</predicate>
           <subject>
               <csid>${itemCSID}</csid>
               <documentType>Citation</documentType>
           </subject>
           <object>
               <csid>a6d62e30-2bd6-439b-b19f</csid>
               <uri>/cspace-services/citationauthorities/urn:cspace:name(citation)/items/a6d62e30-2bd6-439b-b19f</uri>
               <documentType>Citation</documentType>
           </object>
       </relation-list-item>
   </ns3:relations-common-list>
</document>

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 Citation in a CitationAuthority

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

GET /cspace-services/citationauthorities/{citation-auth-id}/items/{id} HTTP/1.1

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 Citation in a CitationAuthority

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

PUT /cspace-services/citationauthorities/{citation-auth-id}/items/{id} HTTP/1.1

You may also PUT a part called

<ns3:relations-common-list>

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 Citation "Drawing", with relations-common-list that has an entry for ${itemCSID} hasBroader "Art" creates a relations record that references both Art and Drawing.  When a PUT is made that does not have the relation for Art, then Drawing has no relations, so the relations record for Drawing==>hasBroader==>Art is deleted, but both "Drawing" and "Art" Citation records remain.

Delete a Citation in a CitationAuthority

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

DELETE /cspace-services/citationauthorities/{citation-auth-id}/items/{id} HTTP/1.1
List Citation instances in a CitationAuthority

Lists existing Citation records, with summary information for each. Follows standard List model. See the documentation of the Citation-List schema, below. List supports the following common parameters for List results, pagination controls and query filters:

  • pgSz for page size
  • pgNum for page number
  • pt for partial-term matching, to support term completion.

Examples:

GET /cspace-services/citationauthorities/{citation-auth-id}/items/ HTTP/1.1
GET /cspace-services/citationauthorities/{citation-auth-id}/items/?pt=foo&pgSz=10 HTTP/1.1

Citation REST payload schemas

The schemas below are abbreviated, and are thus illustrative.  For a full list of the fields that may potentially be present in payloads when creating, updating, or reading individual Citation records, please see the most recent Citation schema (i.e. for an individual Citation term within a CitationAuthority or vocabulary).

Citation instance schema

Create and Update should use the following schema.

On create, the value of inAuthority must match the identifier of the parent CitationAuthority, and will not be modified once the instance is created.

You can view the full set of validation constraints on the data you submit when creating or updating Citation instance records, in the most recent CollectionSpace code, via this Java source code file.

Here's an example payload for creating a new instance:

<?xml version="1.0" encoding="UTF-8"?>
<document name="citations">
   <ns2:citations_common xmlns:ns2="http://collectionspace.org/services/citation" xmlns:ns3="http://collectionspace.org/services/jaxb">
       <inAuthority>6ca3db57-7c96-47b6-b17d</inAuthority>
       <shortIdentifier>Quiscustodietipsoscustodes1367585080203</shortIdentifier>
       <citationTermGroupList>
             <citationTermGroup>
                   <displayName>Quis custodiet ipsos custodes</displayName>
                   <termLanguage>urn:cspace:core.collectionspace.org:vocabularies:name(languages):item:name(eng)'English'</termLanguage>
             </citationTermGroup>
       </citationTermGroupList>

       ...
   </ns2:citations_common>
</document>

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

<?xml version="1.0" encoding="UTF-8"?>
<document name="citations">
   <ns2:collectionspace_core xmlns:ns2="http://collectionspace.org/collectionspace_core/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       ...
       <uri>/citationauthorities/afbb91ca-3988-4524-bada</uri>
       ...
   </ns2:collectionspace_core>
   <ns2:citations_common xmlns:ns2="http://collectionspace.org/services/citation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       ...
       <csid>afbb91ca-3988-4524-bada</csid>
       ...
   </ns2:citations_common>
</document>
Citation-List schema

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:abstract-common-list xmlns:ns2="http://collectionspace.org/services/jaxb">
   <pageNum>0</pageNum>
   <pageSize>40</pageSize>
   <itemsInPage>3</itemsInPage>
   <totalItems>3</totalItems>
   <fieldsReturned>csid|uri|updatedAt|termDisplayName|refName|shortIdentifier</fieldsReturned>
   <list-item>
       <csid>afbb91ca-3988-4524-bada</csid>
       <uri>/citationauthorities/afbb91ca-3988-4524-bada</uri>
       <updatedAt>2012-03-29T00:51:04Z</updatedAt>
       <termDisplayName>Quis custodiet ipsos custodes</termDisplayName>
       <refName>urn:cspace:core.collectionspace.org:citationauthorities:name(Quiscustodietipsoscustodes1367585080203)'Quis custodiet ipsos custodes'</refName>
       <shortIdentifier>Quiscustodietipsoscustodes1367585080203</shortIdentifier>
   </list-item>
   ...
</ns2:abstract-common-list>
  • No labels