Question

Do standards or best practices exist for structuring JSON responses from an API? Obviously, every application’s data is different, so that much I’m not concerned with, but rather the “response boilerplate”, if you will. An example of what I mean:

Successful request:

{
  "success": true,
  "payload": {
    /* Application-specific data would go here. */
  }
}

Failed request:

{
  "success": false,
  "payload": {
    /* Application-specific data would go here. */
  },
  "error": {
    "code": 123,
    "message": "An error occurred!"
  }
}

Answer 1

Yes there are a couple of standards (albeit some liberties on the definition of standard) that have emerged:

1. JSON API – JSON API covers creating and updating resources as well, not just responses.
2. JSend – Simple and probably what you are already doing.
3. OData JSON Protocol – Very complicated.
4. HAL – Like OData but aiming to be HATEOAS like.

There are also JSON API description formats:

• Swagger
  • JSON Schema (used by swagger but you could use it stand alone)
• WADL in JSON
• RAML
• HAL because HATEOAS in theory is self describing.