Best API response format in Json

Question

Which one is best for Rest API response?

1. In here I return some meta information with actual data. Although I am not sure they need to use those meta information or not.

{
    "version": "1.0.0",
    "isError": false,
    "statusCode": 200,
    "message": "Permission Object",
    "data": {
        "id": 1,
        "name": "user create",
        "created_at": "2022-11-30T10:18:20.000000Z"
    }
}

2. In second example I am returning only the relevant data.

{
    "id": 1,
    "name": "user create",
    "created_at": "2022-11-30T10:18:20.000000Z"
}

Give me suggestion if there are other better way.

Answer 1

I noticed you've used the tag REST, so I assume you are thinking about a RESTful API implementation and have some knowledge about RESTful API design.

If you need some best practices, a couple of them I think are useful. here and here .

Looking at your examples, I would prefer the second option, the reasons are:

1. IsError can be determined by the HTTP response, eg 400, 500, 200, 201, so it's redundant.
2. Status and Message are also redundant when the response is successful but could be useful in an error state, like in ASP.NET, you can use the ProblemDetails response (you can customize the way you want).

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "Unable to create a new user due to missing name",
    "status": 400,
    "traceId": "00-0aa7d64ad154a1e1853c413a0def982d-195d3558c90f7876-00"
}

3. version is an interesting one. Usually, it can be included in the request header or URL. If the API cannot handle the version requested, then it should return an error in the problem details.

Thus, I prefer the second option and send a problem details response when there is an error.

Answer 2

An open source CRM with more than 18K start on github uses Laravel-default api resource Project Link Code Example link

Pay attention to status codes Reference

This one is super important. If there's one thing you need to remember from this article, this is probably it:

The worst thing your API could do is return an error response with a 200 OK status code.

It's simply bad semantics. Instead, return a meaningful status code that correctly describes the type of error.

Still, you might wonder, "But I'm sending error details in the response body as you recommended, so what's wrong with that?"

Let me tell you a story.

I once had to use an API that returned 200 OK for every response and indicated whether the request had succeeded via a status field:

{
  "status": "success",
  "data": {}
}

So even though the status was 200 OK, I could not be absolutely sure it didn't fail to process my request.

This kind of design is a real no-no because it breaks the trust between the API and their users. You come to fear that the API could be lying to you.

All of this is extremely un-RESTful. What should you do instead?

Make use of the status code and only use the response body to provide error details.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "Expected at least two items in list."
}

Answer 3

JSON API is a format that works with HTTP. It delineates how clients should request or edit data from a server, and how the server should respond to said requests.