RESTful Java Web Services - Third Edition

Including the version in the resource URI –  URI versioning

In the URI versioning approach, the version is appended along with the URI. An example is as follows:

GET /api/v1/departments HTTP/1.1 

A sample RESTful web API implementation that takes a version identifier as part of the resource URI will look like the following:

//Imports are removed for brevity 
@Path("v1/departments") 
public class DepartmentResourceV1{ 
    @GET 
    @Produces("application/json") 
    public List<Department> findDepartmentsInRange( 
        @QueryParam("offset") @DefaultValue("1") Integer offset,  
        @QueryParam("limit") @DefaultValue("20") Integer limit) { 
 
        return findAllDepartmentEntities(offset, limit); 
    } 
    //Other methods are removed for brevity 
} 

With this approach, if you want to upgrade ...