...
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.
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:
...
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 | 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 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: 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: Entity Body (on Error)
Returns an XML document containing a description of the error. See Common System Specific Elements for details.
Read (Multiple)
...
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 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.
...