Best way to handle JAX-RS REST API URI versioning

Question

The problem with putting it in the URL is that the URL is supposed to represent a resource by location. An API Version is not a location and it not part of the identifier of the resource.

Sticking /v2/ in the URL breaks all existing links that came before.

There is one correct way to specify API versioning:

Put it in the mime-type for the Accept: header that you want. Something like Accept: application/myapp.2.0.1+json

Chain of Responsiblity pattern goes well here especially if there will be significant number of API versions that are different enough to have to have their own handler, that way methods don't get out of hand.

This blog post has an example of what is considered the by some to be the correct approach, i.e. not having the version in the URI: http://codebias.blogspot.ca/2014/03/versioning-rest-apis-with-custom-accept.html

In short, it leverages JAX-RS @Consume annotation to associate the request for a particular version to a specific implementation, like:

@Consumes({"application/vnd.blog.v1+xml", "application/vnd.blog.v1+json"})

I was just wondering why not have a subclass of ProductService called

@Path(/v2/ProductService)
ProductServiceV2 extends ProductService {


}


@Path(/v1/ProductService)
 class ProductService{


}

and only override whatever is changed in v2. Everything unchanged will work the same as in v1/ProductService.

This defintely leads to more # of classes but is one easier way of coding for only whatever is changing in the new version of api and reverting to the old version without duplicating code.