Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Why should JSON have a status property

Tags:

json

rest

I stumbled over a practice that I found to be quite widespread. I even found a web page that gave this a name, but I forgot the name and am not able to find that page on google anymore.

The practice is that every JSON response from a REST service should have the following structure:

{
    "status": "ok",
    "data": { ... }
}

or in an error case:

{
    "status": "error",
    "message": "Something went wrong"
}

My question: What is the point why such a "status" property should be required in the JSON? In my opinion that is what HTTP status codes were made for.

REST uses the HTTP means of communication between client and server, for example the "DELETE" verb should be used for deleting. In the same way, 404 should be used if a resource is not found, etc. So inline with that thinking, any error cases should be encoded properly in the HTTP status.

Are there specific reasons to return a HTTP 200 status code in an error case and have the error in the JSON instead? It just seems to make the javascript conditional branches more complex when processing the response.

I found some cases where status could be "redirect" to tell the application to redirect to a certain URL. But if the proper HTTP status code was used, the browser would perform the redirection "for free", maintaining the browsing history properly.

I picture mainly two possible answers from you:

  • Either there are two quarreling communities with their favorite approach each (use HTTP status always vs. use HTTP status never)
  • or I am missing an important point and you'll tell me that although the HTTP status should be used for some cases, there are specific cases where a HTTP status does not fit and the "status" JSON property comes into play.
like image 701
chiccodoro Avatar asked Jul 11 '12 13:07

chiccodoro


People also ask

What is status JSON?

The JSON-STATUS special register is used to indicate either that a JSON PARSE statement executed successfully or that a nonexception condition occurred during the JSON parse operation.

What is the purpose of status codes in HTTP?

An HTTP status code is a message a website's server sends to the browser to indicate whether or not that request can be fulfilled. Status codes specs are set by the W3C. Status codes are embedded in the HTTP header of a page to tell the browser the result of its request.

Why is it important to indicate proper status codes when giving back API responses?

It is important to use the right status code for a given request because that is the standard way for the client would understand what went wrong with the request it sent to the server.

What would be the ideal response status code when the payload contains invalid JSON?

Sending invalid JSON will result in a 400 Bad Request response. [...] Sending the wrong type of JSON values will result in a 400 Bad Request response .


2 Answers

You are right. I think what you are seeing is a side-effect of people not doing REST correctly. Or just not doing REST at all. Using REST is not a pre-requisite for a well-designed application; there is no rule that webapps have to be REST-ful.

On the other hand, for the error condition, sometimes apps want to return a 200 code but an error to represent a business logic failure. The HTTP error codes don't always match the semantics of application business errors.

like image 140
hvgotcodes Avatar answered Sep 21 '22 05:09

hvgotcodes


You are mixing two different Layers here:

  • HTTP is for establishing (high-level) connections and transferring data. The HTTP status codes thus informs you if and how the connection was established or why it was not. On a successful connection the body of the HTTP request could then contain anything (e.g. XML, JSON, etc.), thus these status code have to define a general meaning. It does not inform you about the correctness or type (e.g. error message or data) of the response.

  • When using JSON for interchanging data you could certainly omit the status property, however it is easier for you to parse the JSON, if you know if it includes the object you were requesting or an error message by just reading one property.

So, yes, it is perfectly normal to return a 200 status code and have a "status": "error" property in your JSON.

like image 25
Jan Gerlinger Avatar answered Sep 21 '22 05:09

Jan Gerlinger