Header value: application/vnd.api+json

Question

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 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 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.

The Multipurpose Internet Mail Extensions (MIME) type (or) media type is a standardized way to indicate the nature and format of a document transferred over the internet. It is standardized in IETF RFC 6838. The Internet Assigned Numbers Authority (IANA) is the official body responsible for keeping track of all official MIME types.

The media type used by JSON API is application/vnd.api+json and it has been properly registered with IANA.

The API+JSON media type is for interoperability between different API's that serve JSON.

It was created with consideration from "thick JavaScript" clients and their needs, but is not specific to them. So, prefixed with vnd (vendor).

Adding few more points on JSON API :

• JSON API is a specification which defines an api specification on how a request and response and should be.
• Allows us to create have a well defined structure (like resource - relationships and it's links etc..)
• Specifies how the REST APIs should react for CRUD operations.
• Allows client to cache the responses.