Versioning RESTful web APIs

You should always version the RESTful web APIs. Versioning of APIs helps you to roll out new releases without affecting the existing customer base as you can continue to offer the old API versions for a certain period of time. Later, a customer can move on to a new version if he/she prefers to do so.

You can version RESTful web APIs in many ways. Three popular techniques for versioning RESTful web APIs are given in this section.

Including the version in resource URI – the 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"...