Standardize and document response schema

[jsejcksn]

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

Code	Description	Uses
200	OK	generic
201	Created	create requests

Fail

Code	Description	Uses
400	Bad request	generic
401	Unauthorized	when requesting protected boxes without API key
404	Not Found	when requesting invalid resources (ID, collection, etc.)
405	Method Not Allowed	e.g. when attempting to PUT a collection endpoint
413	Payload Too Large	not sure if you have a real 10KB limit, but would apply in that case
429	Too Many Requests	you don't state that you rate limit, but including this anyway

Error

Code	Description	Uses
500	Internal Server Error	generic
503	Service Unavailable	I saw issues in the past with Mongo Atlas problems

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 (when status is "fail" or "error": a description of the error or the reason why the request failed)
• data (when status is "success"—might not used in cases like DELETE unless you return the deleted data in the response)

Here's an example response for a PUT request with an invalid ID:

{
  "status": "fail",
  "message": "Invalid record ID"
}

And here's one for a GET request:

{
  "status": "success",
  "data": [
    {
      "_id": "5d776b75fd6d3d6cb1d45c52",
      "name": "Daenerys Targaryen",
      "age": 25,
      "_createdOn": "2019-09-10T09:23:01.105Z"
    },
    {
      "_id": "5d776b75fd6d3d6cb1d45c53",
      "name": "Arya Stark",
      "age": 16,
      "_createdOn": "2019-09-10T09:23:01.105Z"
    }
  ],
}

[jsejcksn]

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.

[harlev]

just make sure these are not breaking changes. Even if it will be "more correct" after the change

[jsejcksn]

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

[vasanthv]

@jsejcksn like @harlev said, it is a breaking changes. It should be considered for next major release.