Should an HTTP API always return a body?

Question

Is there some sort of standard regarding HTTP API responses?

After reading this discourse thread I started to wonder. We are developing our public HTTP JSON API at my work, and we do not return anything when it's not strictly needed (for example a PUT to /resource/{id} only returns 200 when OK or the corresponding 4XX or 5XX code, but no JSON body)

Should we return a generic {"success":true} like they discuss on that link above, or is it ok to return a "void" body and handle everything with http response codes?

Answer 1

Regarding PUT, but applies to POST as well. The HTTP specification section 9 is a little empty on rules or even advice (SHOULD) when it comes to the scenario that you are describing. The line relevant to your question is most closely covered by:

If a new resource is created, the origin server MUST inform the user agent via the 201 (Created) response. If an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.

I do not think I would lose any sleep over it, but I would ask, what do you gain by adding the chunk of JSON into the response? You've just bulked out (OK, bulked might be overkill!) the response repeating less accurately what the status code should already have told you. If your PUT resulted in a new object return 201 (as is the intention of PUT), if it updated an object return 204.

Incidentally, API aside, instead of 200, if you don't return anything use 204.

Assuming that you are developing a set of RESTful interfaces, there is no standard per se, so whatever you do, document it well,, provide examples and everything will be alright.

Answer 2

The base HTTP standard does not mandate that there be a document returned with a response. For economy's sake, when an HTTP status conveys all that's required the body would be wasteful. However, there are standards built on top of HTTP that add new rules.

There is an open JSON API standard that specifies:

• A JSON object MUST be at the root of every JSON API response document. (italics represent what I added to clarify the text)

Unfortunately, the standard doesn't specify how to represent an empty document, and it is a work in progress. At best I'd use it as a guideline.

Some applications (like ElasticSearch) provide a full JSON api, and always have some metadata so you can have a better idea of how the server is managing your data. The standard response object tells you about the health of the index, if the request resulted in an error, how many nodes were affected, etc. ElasticSearch uses "application/json" for the mime-type so it's unlikely they are applying the guidelines in the jsonapi.org standard.

JQuery and similar Javascript frameworks assume that there will always be a document. The question is how much error checking do you want to force on your API consumers? If you come up with a standard format for all responses that is only extended based on the type of request, you satisfy the need for a return document, and can facilitate easier debugging by your API consumers.

Answer 3

No for example, for 204 responses we must not include message body. {success|status|isSuccessful: true} is redundant.

In practice (or should I say in later version of jquery), empty response for application/json content type raises error. I kind of understand the argument that because it's application/json it must have a valid json body. So, empty response for application/json content type would be 'null' or '{}' which are valid json.

There's another way which should work for jquery, that is not returning application/json for empty responses. Just use text/plain or something and make sure client can handle that type.

Note I can only remember 204 for explicitly forbid returning message body. What we've found is we can't always use 204. The problem is MSIE drop response header for 204 responses, so there's no content and headers, which is bad. Since many are using MSIE, we had to change it to 200 status.

Answer 4

I would not return simply a success status in the response, the HTTP error code only signals success or error. I'd only include the response itself to add detailed error information such as application-specific error codes or error messages.

For PUT, PATCH and POST requests you typically return the state of the resource after the request has been applied, not an empty response.

For POST requests that represent an action instead of simply creating a resource (not very RESTful, but still useful in practice), which doesn't have useful data to return, I'd return a response consisting of an empty JSON object, i.e. {}. That way the client gets a valid response and adding some information later on is unlikely to break it.

For DELETE requests returning 204 and an empty body is pretty common, which makes sense since the resource doesn't exist afterwards.

Answer 5

No but it will help for consistency of your code. It also good for debugging purposes. It will also a big help in the maintenance of the website. Remember this: Error code is for machine, Error message is for human. So I am suggesting for you to use a response body. Anyway, its negative effect is just minimal(just a few bytes sent over the network) compared to its benefits. Another thing, it will also avoid you from forgetting to write a message body when it is needed.

Answer 6

I would suggest returning only what is needed + a little clarification.

For example, depending on how your API is to be used, you could include a copy of the object, as is exists after being saved.

So a POST of {key: 123} might return {key: 123, foo: 'bar'}.

The basic idea is it is better to return the object then to have to query for it again.

That said, of your API consumers don't need the object there's no need to return it.

I usually return {success: true} or some such, when there is no object required on POST PUT and PATCH because it makes it easier for the receiving end. That said, it's better 99% of the time to return the saved representation of the object, it's rare that they won't need it anyway, and it's "cheaper" to send it all in one request then in two.

To be specific, in a lab it's perfectly find to handle everything with just status codes, in the real world, it's much better to return some data, even if redundant, so that API consumers can easily under stand what your trying to say.

Returning 200 {success: true} lets people write code both ways:

if response.code == 200
  do stuff
end

and

if response.body.success
  do stuff
end

in addition it's not that hard to do on your side.

Lastly, (sorry for the poos answer structure), by providing a public JSON api your giving up a lot of control on how it's going to be used. Some clients may react different to different bodies (or lack there of) or status codes.