Standard JSON API response format?

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

The RFC 7807: Problem Details for HTTP APIs is at the moment the closest thing we have to an official standard.

Answer 2

I will not be as arrogant to claim that this is a standard so I will use the "I prefer" form.

I prefer terse response (when requesting a list of /articles I want a JSON array of articles).

In my designs I use HTTP for status report, a 200 returns just the payload.

400 returns a message of what was wrong with request:

{"message" : "Missing parameter: 'param'"}

Return 404 if the model/controler/URI doesn't exist

If there was error with processing on my side, I return 501 with a message:

{"message" : "Could not connect to data store."}

From what I've seen quite a few REST-ish frameworks tend to be along these lines.

Rationale:

JSON is supposed to be a payload format, it's not a session protocol. The whole idea of verbose session-ish payloads comes from the XML/SOAP world and various misguided choices that created those bloated designs. After we realized all of it was a massive headache, the whole point of REST/JSON was to KISS it, and adhere to HTTP. I don't think that there is anything remotely standard in either JSend and especially not with the more verbose among them. XHR will react to HTTP response, if you use jQuery for your AJAX (like most do) you can use try/catch and done()/fail() callbacks to capture errors. I can't see how encapsulating status reports in JSON is any more useful than that.

Answer 3

Their is no agreement on the rest api response formats of big software giants - Google, Facebook, Twitter, Amazon and others, though many links have been provided in the answers above, where some people have tried to standardize the response format.

As needs of the API's can differ it is very difficult to get everyone on board and agree to some format. If you have millions of users using your API, why would you change your response format?

Following is my take on the response format inspired by Google, Twitter, Amazon and some posts on internet:

https://github.com/adnan-kamili/rest-api-response-format

Swagger file:

https://github.com/adnan-kamili/swagger-sample-template

Answer 4

JSON-RPC 2.0 defines a standard request and response format, and is a breath of fresh air after working with REST APIs.

Answer 5

Google JSON guide

Success response return data

{
  "data": {
    "id": 1001,
    "name": "Wing"
  }
}

Error response return error

{
  "error": {
    "code": 404,
    "message": "ID not found"
  }
}

and if your client is JS, you can using if ("error" in response) {} to check if there is error.

Answer 6

Following is the json format instagram is using

{
    "meta": {
         "error_type": "OAuthException",
         "code": 400,
         "error_message": "..."
    }
    "data": {
         ...
    },
    "pagination": {
         "next_url": "...",
         "next_max_id": "13872296"
    }
}