Header value: application/vnd.api+json

The media type application/vnd.api+json refers to JSON API. You can read about it in great detail here.

In short, JSON API is an opinionated and well reasoned:

…specification for how a client should request that resources be fetched or modified, and how a server should respond to those requests.

The first is an API specific media type. The vendor prefix (vnd.) indicates that it is custom for this vendor. The +json indicates that it can be parsed as JSON, but the media type should define further semantics on top of JSON.

The second just means that the content is JSON. This is in general not very useful, though, because it does not define what the JSON values mean.

A good starting point to read about this would be on Wikipedia, but for more details you can always follow the links to the corresponding RFCs on that page.

If you're not sure, use application/json -- it's the generic MIME type that only requires the data you return to be a well-formed JSON.

---

The application/vnd.api+json MIME type is reserved for communication using the (confusingly named) "JSON API" protocol.

"JSON API" in this context does not mean any API based on HTTP and JSON. It's not a fully-specified API either - rather it's a framework for building APIs that allow the client to fetch and modify interrelated entities. For example, a blog application could implement an API conforming to the "JSON API" specification, that allows fetching last 10 articles by a given author, with metadata and comments for each article, in a single HTTP request.

The specification defines, in particular:

• the specific way a request should be formed (i.e. what URL parameters control sorting and pagination and the data included in the output);
• the specific structure of the JSON document in the response, for example:

  A document MUST contain at least one of the following top-level members:

  • data: the document’s “primary data”
  • errors: an array of error objects
  • meta: a meta object that contains non-standard meta-information.

  The members data and errors MUST NOT coexist in the same document.