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

68
votes

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 some other type?

The second question is with regard to the HTTP status code for error conditions. If my REST API is returning an error state, I am returning as JSON

{ result: "fail", errorcode: 1024, errormesg: "That sucked. Try again!" }

Should the HTTP status code remain at 200 OK?

6
jsonresthttpmime-typesrestapi
All the answers to this seem to assume that a browser is involved. My REST application sends and responds with json messages. All serialization and de-serialization is done by internally the client and server. Third party browsers have nothing to do with any of it, it's all very specific machine to very specific non-public machine. In this case the "application/ whatever_type" makes zero difference, it's all just text. "application/json" does reinforce that the data is json, but only as commentary, and this is already the very first thing anyone working with the API would know. – MickeyfAgain_BeforeExitOfSO
@mickeyf - The fact that browsers support the HTTP protocol does not mean that M2M applications should not. If you want to write an application that doesn't support Accept and Content-Type headers (tools.ietf.org/html/rfc7231#section-3.1.1.5) you are free to do so, however other M2M developers may want to support multiple media-types (e.g., application/cbor) in a standard manner. – Dave

6 Answers

79
votes

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.

10
votes

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

10
votes

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.

6
votes

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.

1
votes

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