1. Timothy Corbett-Clark
  2. rest-api-blueprint


Clone wiki

rest-api-blueprint / MimeTypes

Mime Types

See RFC4288.

My preference is to only support JSON and not (for example) to support XML as well. For a fuller exposition, see this.

Further, although there is a logical argument to use a bespoke mime type (e.g. Huddle, github, and Sun Cloud all do so), at least for now I am choosing not to do so for reasons of simplicity. By "simplicity" I mean avoiding the need to register, have mimetype "best matching" work out of the box, be able to think like a duck (duck typing), and being able to use tools with only intermediate knowledge of the mediatype specificity (see this). Well known API's which take this looser approach to mimetypes include Amazon Cloud and Salesforce.


Omitting the Content-Type header on an incoming HTTP request is permitted on a PUT or POST (when it indicates no data). If there is any content then it must be valid JSON with Content-Type: application/json. Anything else is rejected with a 406.


For non-errors, JSON is always returned except with HTTP GET requests for which HTML is preferred over JSON (as per the Accept header). These are interpreted as a request for documentation, which is returned as HTML.

For errors, JSON is returned if it is preferred over HTML (again as indicated by the Accept header), otherwise HTML is returned.

In all cases the Content-Type is set appropriately and will therefore be either application/json or text/html.