| Warning |
|---|
This document is currently in the process of being replaced by Common Services REST API documentation. |
This document provides suggested templates for REST-based APIs, for potential adoption by many of the services in CollectionSpace's services layer. This implements part of the work described in the "REST Service Contracts" section of Web Services - Paradigms and Contracts /wiki/spaces/collectionspace/pages/666274329.
Some generic message payloads and envelopes that are to be used with the proposed APIs below, such as the message payloads to be returned in a response when an error occurs, are detailed in Common System Specific Elements.
...
...
This document is in process, and is currently incomplete. It has not yet been reviewed or accepted by the CollectionSpace Services Team.
REST-based APIs, and their associated client-visible resource models, are suggested below for the three major types of CollectionSpace services: entity services, relation (association) services, and task services:
...
- text/plain (for plain text)
- applicationmultipart/xml mixed (for generic XML content)
See Questions or Issues, below.
...
Response: Entity Body (on Error)
Returns an XML document containing a description of the error. See Common System Specific Elements for details.
As RESTful Service - Ajax Patterns notes, "Error responses should ... be in human-friendly language and with examples and hyperlinks."
...
Response: Entity Body (on Error)
Returns an XML document containing a description of the error. See Common System Specific Elements for details.
Questions or Issues
...
Response: Status Codes
Code | Meaning | Returned When | ||||
|---|---|---|---|---|---|---|
201 400 | Created | A new instance of the resource was created successfully within /{resources_as_a_plural_noun}. | 400 | Bad Request | The resource could not be created because the Bad Request | The resource could not be created because the data sent in the entity body of the request was bad, as determined by the service. |
401 | Unauthorized | The resource could not be created because the client submitting the request either has not provided authentication credentials, or authentication failed (e.g. due to an invalid username or password) after such credentials were provided. | ||||
403 | Forbidden | The resource could not be created because the client submitting the request was not authorized to create new resources in this container. | ||||
409 | Conflict | The resource could not be created because the submitted data would create a duplicate (non-unique) resource, as determined by the service. | ||||
500 | Internal Server Error | A service error prevented the resource from being created. |
Response: Content-Type
application/xml
Response: Entity Body (on Success)Location
Returns a representation of the URL for the newly-created object.
Response: Entity Body (on Success)
Returns a representation of the newly-created resource, as an XML document conforming to the schema used by the service.
Returns an empty entity body.
Response: Entity Body (on Error)
Returns an XML document containing a description of the error. See Common System Specific Elements for details.
Questions or Issues
...
Code | Meaning | Returned When |
|---|---|---|
200 | OK | A representation of the resource was read (i.e. returned) successfully. |
401 | Unauthorized | The resource could not be read because the client submitting the request either has not provided authentication credentials, or authentication failed (e.g. due to an invalid username or password) after such credentials were provided. |
403 | Forbidden | The resource could not be returned read because the client submitting the request was not authorized to read it. |
404 | Not Found | The resource at /{resources_as_a_plural_noun}/{resource_identifier} does not exist. |
500 | Internal Server Error | A service error prevented the resource from being read. |
Response: Content-Type
application multipart/xmlmixed
Response: Entity Body (on Success)
Returns a representation of the requested resource, as an XML document conforming to the schema used by the service.as one or more documents conforming to the schema used by the service.
Consists of one or more MIME message parts, each separated by a message-specific boundary line, and each part containing a separate document. Each of these parts of the message is currently of Content-Type: application/xml.
The MIME message part whose label ends in _common contains a document conforming to the "common" schema for a particular entity; that is, the schema that will be present for all tenants in a specific deployment. The "common" schema is also supported by search and other functionality which does not apply to extension schema. If there are other MIME message parts present, ending in a name other than _common, these parts will typically represent one or more extension schema, specific to the current tenant.
An example, showing two MIME message parts, each containing XML documents representing part of a CollectionObject: one containing the fields in an extension schema (collectionobject_naturalhistory), and the second containing the fields in the common schema (collectionobjects_common).
| Code Block |
|---|
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Powered-By: Servlet 2.4; JBoss-4.2.3.GA (build: SVNTag=JBoss_4_2_3_GA
date=200807181439)/JBossWeb-2.0
Content-Type: multipart/mixed;
boundary=ab8d331a-9720-45c9-a629-2c71050f1720
Content-Length: 1643
Date: Wed, 02 Dec 2009 23:18:13 GMT
--ab8d331a-9720-45c9-a629-2c71050f1720
label: collectionobjects_naturalhistory
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<ns2:collectionobjects_naturalhistory
xmlns:ns2="http://collectionspace.org/services/collectionobject/domain/naturalhistory"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://collectionspace.org/services/collectionobject/domain/naturalhistory
http://collectionspace.org/services/collectionobject/domain/collectionobjects_naturalhistory.xsd">
<nh-string>test-string</nh-string>
<nh-int>999</nh-int>
<nh-long>9999</nh-long>
</ns2:collectionobjects_naturalhistory>
--ab8d331a-9720-45c9-a629-2c71050f1720
label: collectionobjects_common
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<ns2:collectionobjects_common
xmlns:ns2="http://collectionspace.org/services/collectionobject"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://collectionspace.org/services/collectionobject
http://services.collectionspace.org/collectionobject/collectionobjects_common.xsd">
<otherNumbers>
<otherNumber>urn:org.collectionspace.id:24082390</otherNumber>
<otherNumber>urn:org.walkerart.id:123</otherNumber>
</otherNumbers>
<objectNumber>updated-objectNumber-1259718776712</objectNumber>
<briefDescription>Papier mache bird mask with horns, painted red with black
and yellow spots. Puerto Rico. ca. 8&quot; high, 6&quot; wide,
projects 10&quot; (with horns).</briefDescription>
<objectName>updated-objectName-1259718776712</objectName>
</ns2:collectionobjects_common>
--ab8d331a-9720-45c9-a629-2c71050f1720--
|
Response: Entity Body (on Error)
Returns an XML document containing a description of the error. See Common System Specific Elements for details.
Read (Multiple)
...
| Code Block |
|---|
GET /{resources_as_a_plural_noun}/{resource_identifier}/{typed_or_child_resources_as_a_plural_noun}
|
| Code Block |
|---|
GET /{resources_as_a_plural_noun}/{resource_identifier}/
{typed_or_child_resources_as_a_plural_noun}?{optional_query_parameters ...}
|
...
Some possible examples of query parameters to modify read (multiple) requests. These in part come from Common System Specific Elements:
?orderby={information_unit}
Requests that hyperlinks or full records be returned in the natural sort order of a particular information unit (field or data element). Defaults to ascending order if the sortorder query parameter isn't present.
...
Response: Entity Body (on Error)
Returns an XML document containing a description of the error. See Common System Specific Elements for details.
Questions or Issues
...
Code | Meaning | Returned When |
|---|---|---|
200 | OK | A new instance of the resource was updated successfully at /{resources_as_a_plural_noun}/{resource_identifier}. |
400 | Bad Request | The resource could not be updated because the data sent in the entity body of the request was bad, as determined by the servicethe entity body of the request was bad, as determined by the service. |
401 | Unauthorized | The resource could not be updated because the client submitting the request either has not provided authentication credentials, or authentication failed (e.g. due to an invalid username or password) after such credentials were provided. |
403 | Forbidden | The resource could not be updated because the client submitting the request was not authorized to update resources in this container. |
404 | Not Found | The resource at /{resources_as_a_plural_noun}/{resource_identifier} does not exist. |
500 | Internal Server Error | A service error prevented the resource from being updated. |
...
Response: Entity Body (on Error)
Returns an XML document containing a description of the error. See Common System Specific Elements for details.
Questions or Issues
...
Code | Meaning | Returned When |
|---|---|---|
200 | OK | The resource was successfully deleted. |
401 | Unauthorized | The resource could not be deleted because the client submitting the request either has not provided authentication credentials, or authentication failed (e.g. due to an invalid username or password) after such credentials were provided. |
403 | Forbidden | The resource could not be deleted because the client submitting the request was not authorized to delete it. |
404 | Not Found | The resource at /{resources_as_a_plural_noun}/{resource_identifier} does not exist. |
500 | Internal Server Error | A service error prevented the resource from being updateddeleted. |
Response: Content-Type
application/xml
...
Response: Entity Body (on Error)
Returns an XML document containing a description of the error. See Common System Specific Elements for details.
Search
| Note |
|---|
This section is an in-process placeholder. The notes below are very rough at present. |
...
In the case of error responses, the status code MUST be supplemented by a standardized payload in the entity body of the response, containing a more detailed and complete description of the error. This payload MUST be both human and machine-readable. See Common System Specific Elements for details.
As RESTful Service - Ajax Patterns notes, "Error responses should ... be in human-friendly language." That document goes on to suggest that such responses include "examples and hyperlinks," if possible. However, while that is desirable, it is not required.
...