...
REST-based APIs for Entity Services
...
Where possible, naming conventions should be consistent - after reflecting software-specific requirements or idioms - across all of the artifacts that pertain to a path element, including source code files, schemas, and the like.
Status Codes
HTTP provides a rich set of over 40 status codes: numeric codes sent by server to client indicating what happened in response to a request.
Supporting each of these status codes makes sense when the client is a web browser. In other contexts, however, it is desirable to keep the number of status codes returned with responses to a minimum. It can be burdensome for RESTful API clients to support each of these codes, as well as for human programmers to understand their sometimes subtle distinctions. As well, some of these codes are relatively esoteric, and may not apply to interactions in a RESTful transaction.
It is proposed here that any particular CollectionSpace services select from a subset of between five and nine of these status codes, as may be relevant to the service. Even with such a restricted subset, it is argued here that relevant success and error conditions can be successfully reflected. This number also conforms to the seven plus or minus two convention, reflecting limitations of human short-term memory.
The following is the subset of HTTP status codes that may be selected from when returning a response to the client:
Success Responses
Code | Meaning | Returned When (Genericized) |
|---|---|---|
200 | OK | The resource was successfully accessed. (This is a generic success code that may be used with any operation, including both read-only and read-write.) |
201 | Created | A new instance of the resource was created successfully. |
Error Responses
Code | Meaning | Returned When (Genericized) |
|---|---|---|
400 | Bad Request | The resource could not be accessed because the data sent in the request (typically in the entity body or in the query parameters) was bad, as determined by the service. |
403 | Forbidden | The resource could not be accessed because the client submitting the request was not authorized to accessed it. |
404 | Not Found | The resource does not exist. |
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 accessed. |
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, that is desirable, and is not required.
References
Normative Guides to Developing RESTful Services
...