What MIME type if JSON is being returned by a REST API?

Question

My REST API returns JSON.

I\'m currently returning text/plain as the MIME type, but it feels funny. Should I be returning application/x-javascript or s

Answer 1

The MIME type of JSON is

application/json

http://www.ietf.org/rfc/rfc4627.txt

http://www.iana.org/assignments/media-types/application/

More specifically here:

http://www.ietf.org/rfc/rfc4627.txt

Answer 2

The proper Content-type to return is application/json, according to RFC 4627, which also registers the MIME type IANA (and indeed, it shows up on IANA's page). Of course, if you were to write a client, you would want to be more liberal in what you accept, and also accept others such as text/json and text/x-json.

Now, if there is an error you should not return HTTP 200, that's fundamentally non-RESTful. I know that sometimes there's not an exact match for your error, but choose the closest 4XX (client's fault) or 5XX (server's fault) errors in RFC 2616 Sections 10.4-10.5, and be more precise in the JSON.

Answer 3

The JSON spec suggests application/json, and that seems to be supported by the IETF and IANA registry.

On the second question, I think if the message handling fails in some way you should return a structured and standard error response as a JSON message; only if there is a failure to deliver the message to the backend handler for some reason should you consider an HTTP error code.

Update 2014-06-27: The days where clients (browsers) only worked with a 200 response are long past and the prevailing advice for RESTful APIs is to use HTTP response codes appropriate for the response, 2xx for successful responses (e.g. 201 Created for PUT; 204 No Content for DELETE) and 4xx and 5xx for all error conditions, including those from the API itself.

Answer 4

No, you shouldn't return 200 in an error condition.

It's ok to repeat the status code, or to include a more detailed error code in the response payload.

Answer 5

I prefer to reply with both an HTTP error status and application specific payload.

Answer 6

If by "REST API" you mean that you want to follow a REST architecture then the media type to use is determined by the functionality you want to expose through the REST API. Do you want to be able to create new objects? Query a list of objects? Edit an object? If so, then a good RESTful media type to use might be vnd.collection+json because it defines a hypertext linked interface to manipulate a collection of json objects.

Note: A RESTful API could use the media type application/json, but this media type doesn't have a hypertext linked RESTful interface, so it would be an end point in the state change.

It's also completely acceptable to follow a web API architecture, where HTTP RPC calls return application/json objects, and other HTTP RPC calls manipulate those objects, and there is no hypertext link interface for using and navigating the state changes. But this isn't REST.

I like this description of REST (from the creator of REST):

REST APIS must be hypertext driven

In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period.

Also, from the discussion of that post is this example of a RESTful application: Lost Boys's Spam-E REST Application