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 the version for a resource, you will have to build a new resource class that takes the latest API version as the Path parameter. To avoid code duplication, you can subclass the existing resource class and override only the modified resource methods as shown here:

//Imports are removed for brevity 
@Path("v2/departments") 
public class DepartmentResourceV2 extends DepartmentResourceV1{ 
    @GET 
    @Produces("application/json") 
    @Override 
    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 
} 

Many big players (Twitter, Facebook, and so on) use the URI versioning approach for versioning the APIs.

Conceptually, this is the simplest solution for API versioning. However, there are certain drawbacks associated with this approach:

• As the resource URI changes with each release, client applications may have to change all the existing URI references in order to migrate to a new release. The impact may be minimal if all the resource URIs are localized and stored in a configuration file.
• This approach may disrupt the concept of HATEOAS.
• Since the URI path for an API gets updated for each change in the REST resource class, you may experience a large URI footprint over a period of time. This may result in a code maintenance issue for both the client and the server.
• If the URI is versioned, the cache may contain multiple copies of each resource, one for every version of the API.