0

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" } }
  1. 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.

Improve this question
2
  • 2
    This sounds like a non-constructive, subjective question. I think a better question would be to ask for common scenarios where one approach is necessary or more appropriate than the other. Having a community wiki answer post could be useful to prevent an explosion of partially overlapping answers. Even then, the question might be too broad. But I'm not certain. Commented Dec 12, 2022 at 0:00
  • This article on Rest best practices answers some of your questions: learn.microsoft.com/en-us/azure/architecture/best-practices/… Commented Dec 16, 2022 at 7:59

3 Answers 3

Reset to default
6
+50

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, e.g. 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" }
  1. 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.

Improve this answer
Sign up to request clarification or add additional context in comments.

2 Comments

The simple answer is to let the api respond the minimal quantity of information needed by the client side. I usually make sure I'm answering with the right status code and provide the most minimalistic payload to the client.
"traceId" in the example, should be actually "instance" according to Problem Details RFC9457
1

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." }
Improve this answer

Comments

-2

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.

Improve this answer

1 Comment

As it’s currently written, your answer is unclear. Please edit to add additional details that will help others understand how this addresses the question asked. You can find more information on how to write good answers in the help center.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.