RESTful Java Web Services - Third Edition

Including the version in a custom HTTP request header – HTTP header versioning

The HTTP header versioning approach uses a custom header field to hold the API version. While requesting for a resource, the client sets the version in the header along with other information (if any). The server can be built to use the version information sent by the client in order to identify the correct version of the resource.

The following example uses a custom header to specify the API version that the client is looking for:

GET /api/departments HTTP/1.1 
api-version: 1.0 

The API implementation can read the request header via @javax.ws.rs.HeaderParam:

//Other imports are omitted for brevity import javax.ws.rs.HeaderParam; @GET @Produces("application/json") ...