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

This is called MIME type versioning or content negotiation. When you develop REST APIs you may want to add different versions of that API in future, say v1, v2 etc..., and different users of our API should be able to call the desired version. Now there can be different approaches to solve this API versioning problem like URI Versioning, Parameter Vesioning, Header Versioning or MIME versioning.

Let's talk about MIME Versioning with an example.

Let's suppose we have a Person entity that our REST API responds with:

public class Person {

   private String name;
   private String email;

   public Person() {
   }

   public Person(String name, String email) {
       this.name = name;
       this.email = email;
   }

   public String getName() {
       return name;
   }

   public void setName(String name) {
       this.name = name;
   }

   public String getEmail() {
       return email;
   }

   public void setEmail(String email) {
       this.email = email;
   }

}

But what we want is that the caller of our API should mention a version and based on that we will respond with the appropriate person. Below is our RestController :

@RestController
public class PersonController {
    
    @GetMapping(path = "/person", produces = "application/vnd.company.api-v1+json")
    public Person getPersonV1() {
        return new Person("Mr. ABC", "[email protected]");
    }

    @GetMapping(path = "/person", produces = "application/vnd.company.api-v2+json")
    public Person getPersonV2() {
        return new Person("Mr. XYZ", "[email protected]");
    }
}

Now I hit our API with different versions and get the appropriate response from the API. Please check the output below:

application/vnd.company.api-v1+json Requesting version 1

application/vnd.company.api-v2+json Requesting version 2

So we can see how we can version our REST API using this MIME versioning approach. Different organizations use different approach for API versioning.