CODEWITHSUNDEEP
resthttp-response-codes
Gerald Mücke
Gerald Mücke

Reputation: 11122

REST API Design: Respond with 406 or 404 if a resource is not available in a requested representation

We have a REST API to fetch binary files from the server.

The requests look like

GET /documents/e62dd3f6-18b0-4661-92c6-51c7258f9550 HTTP/1.1
Accept: application/octet-stream

For every response indicating an error, we'd like to give a reason in JSON. The problem is now, that as the response is not of the same content type as the client requested.

But what kind of response should the server produce?

Currently, it responds with a 

HTTP / 1.1 406 Not Acceptable
Content-Type: application/json
{
  reason: "blabla"
  ...
}

Which seems wrong to me, as the underlying issue is, that the resource is not existing and not the client requesting the wrong content type.

But the question is, what would be the right way to deal with such situations?

Upvotes: 1

Views: 1089

Answers (1)

cassiomolin
cassiomolin

Reputation: 130877

If no representation can be found for the requested resource (because it doesn't exist or because the server wishes to "hide" its existence), the server should return 404.

If the client requests a particular representation in the Accept header and the server is not available to provide such representation, the server could either:

  • Return 406 along with a list of the available representations. (see note** below)
  • Simply ignore the Accept header and return a default representation of the resource.

See the following quote from the RFC 7231, the document the defines the content and semantics of the HTTP/1.1 protocol:

A request without any Accept header field implies that the user agent will accept any media type in response. If the header field is present in a request and none of the available representations for the response have a media type that is listed as acceptable, the origin server can either honor the header field by sending a 406 (Not Acceptable) response or disregard the header field by treating the response as if it is not subject to content negotiation.

Mozilla also recommends the following regarding 406:

In practice, this error is very rarely used. Instead of responding using this error code, which would be cryptic for the end user and difficult to fix, servers ignore the relevant header and serve an actual page to the user. It is assumed that even if the user won't be completely happy, they will prefer this to an error code.

** Regarding the list of available representations, see this answer.

Upvotes: 1

Related Questions