The media type versioning approach adds the version information to the media content type. You can do this by introducing custom vendor media types that hold the version information along with the media type details. The version information in the Accept header takes the following form:

Accept: application/vnd.{app_name}.{version}+{response_type} 

The vnd part that you see in the Accept header is based on RFC 6838. The vnd keyword indicates the custom vendor-specific media types. More details are available at https://tools.ietf.org/html/rfc6838.

When you use this approach for versioning APIs, the client has to specify the version in the HTTP Accept header, as shown in the following example:

GET /api/v1/departments 
Accept: application/vnd.packtpubapi.v1+json 

A sample RESTful web API implementation that uses the media type versioning approach is shown here for your reference:

@Path("departments") 
@Produces({"application/json", "application/vnd.packtpub.v1+json"}) 
@Consumes({"application/json", "application/vnd.packtpub.v1+json"}) 
public class DepartmentResource{ 
    //The following method is a modified implementation 
    //to read the list of employees, so the version number has been incremented 
    @GET 
    @Produces({"application/vnd.packtpub.v2+json"}) 
    public List<Department> findDepartmentsInRangeV2( 
        @QueryParam("offset") @DefaultValue("1") Integer offset,  
        @QueryParam("limit") @DefaultValue("20") Integer limit) { 
        return findDepartmentEntitiesWithDetails(offset, limit); 
    } 
 
    @GET 
    public List<Department> findDepartmentsInRangeV1(  
        @QueryParam("offset") @DefaultValue("1") Integer offset,  
        @QueryParam("limit") @DefaultValue("20") Integer limit){ 
        return findDepartmentEntities(offset, limit); 
    } 
 
} 

The preceding implementation has two methods annotated with different media type versions. At runtime, the Jersey framework automatically picks up a method to serve a request on the basis of the media type version information present in the Accept header parameter.

Many new API vendors have started supporting this approach. For example, GitHub uses the Accept header approach for versioning its APIs.