...
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: 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: 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
...
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: 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.
...