Open jsejcksn opened 4 years ago
To extend this further, you could also consider implementing a caching mechanism using Etags, and utilizing the 304
status code. However, that might be best discussed in a separate issue.
just make sure these are not breaking changes. Even if it will be "more correct" after the change
@harlev I don’t see any documented response standards. Is there something to break?
If it is decided that these suggestions would introduce breaking changes, then they're suggestions for the next major version.
@jsejcksn like @harlev said, it is a breaking changes. It should be considered for next major release.
It would be useful to standardize and document the responses for each operation, such as the status code, response body, etc.
Status codes
See https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
Here are some suggested examples:
Success
create
requestsFail
PUT
a collection endpointError
Body
The response body would also benefit from being standardized with static or conditional fields. As a suggestion, you could provide the following standard response fields on the body:
status
(one of: "success", "fail", or "error")message
(whenstatus
is "fail" or "error": a description of the error or the reason why the request failed)data
(whenstatus
is "success"—might not used in cases likeDELETE
unless you return the deleted data in the response)Here's an example response for a PUT request with an invalid ID:
And here's one for a GET request: