68

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?

Henke
  • 1,466
  • 2
  • 9
  • 22
ashitaka
  • 3,828
  • 7
  • 34
  • 42
  • 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 Feb 08 '17 at 15:32
  • 1
    @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 (https://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 Jun 25 '18 at 21:08

6 Answers6

79

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.

Lawrence Dol
  • 59,198
  • 25
  • 134
  • 183
  • Thanks for the link to the JSON spec. I found another stackoverflow question that points to another MIME type "text/x-json". Not sure what's the difference. http://stackoverflow.com/questions/95554/overriding-a-mime-type-in-rails – ashitaka Jan 01 '09 at 03:38
  • 7
    For practical reasons (say for example you've got Flex's horrific HTTP client in the mix), sometimes you have to use 200 for everything. However, under normal circumstances, you want to use the most appropriate HTTP status code for the situation. – Bob Aman Oct 31 '09 at 05:08
  • 2
    @ashitaka: That other question specifically asks how to set JSON to text/x-json. It makes no claim as to that being the correct media-type for JSON. – Lawrence Dol May 25 '11 at 18:50
20

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

inquam
  • 11,960
  • 14
  • 53
  • 95
10

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.

Julian Reschke
  • 35,455
  • 7
  • 78
  • 83
10

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

  • 2
    It seems that David has left SO, but can anyone else support above statement and bring some arguments, why this is a good (or bad) practice? As per Software Monkey's answer above, I see, that returning a HTTP error with a valid JSON response is a wrong idea. Server should send back HTTP error only, if there is a true error. – trejder Dec 18 '13 at 10:00
6

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.

LukeShu
  • 75
  • 1
  • 6
1

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

Jason
  • 326
  • 2
  • 3