Let's consider the following URI /rooms/{roomId} that provides access to a room resource, as described in The Data-Transfer-Object design pattern section. We want to add a new field containing a URL pertaining to a picture of the room (pictureUrl). Such a change is forward-compatible and does not require specific treatment for clients to continue consuming the service.

Now, we realize that having more than one picture would improve user engagement. We could simply add a new field along with the existing picture URL. However, it makes more sense to just replace the picture URL field with a list of URLs (pictureUrls). This change is not backward compatible. Therefore, we need to create a new version of our service to ensure that existing clients will continue working. To do so, we include the version in resource URIs.

With this approach, /rooms/{roomId} becomes /v{versionNumber}/rooms/{roomId}. For example, the URI for a room with ID #1 in our first API is /v1.0/rooms/1, and it will contain the pictureUrl field. The room in our new version will be accessible with /v1.1/rooms/1 and return the list of picture URLs.

In the previous example, we produced different representations of our Rooms. We could therefore consider managing versioning with MIME type versioning. The following code snippet illustrates how we can achieve this with Spring Web:

@RequestMapping(value = "/{roomId}", method = RequestMethod.GET)
public RoomDTO getRoom(@PathVariable("roomId") long id) {
  Room room = inventoryService.getRoom(id);
  return new RoomDTO(room);
}

@RequestMapping(value = "/{roomId}", method = RequestMethod.GET, consumes = "application/json;version=2")
public RoomDTOv2 getRoomV2(@PathVariable("roomId") long id) {
  Room room = inventoryService.getRoom(id);
  return new RoomDTOv2(room);
}

With this setup, getRoomV2() will be invoked when requests have their Content-Type headers set to application/json;version=2. Otherwise, getRoom() will handle requests for the access of rooms.

Besides the two approaches described previously, one could consider using other solutions. For example, a dedicated header, such as X-API-Version, could be used to specify which API version should be used. The following code will handle requests to get rooms for version 3 of our API:

@RequestMapping(value = "/{roomId}", method = RequestMethod.GET, headers = {"X-API-Version=3"})
public RoomDTOv3 getRoomV3(@PathVariable("roomId") long id) {
  Room room = inventoryService.getRoom(id);
  return new RoomDTOv3(room);
}

In this example, we instructed Spring to map requests to /rooms/{roomId} containing the header, X-API-Version, with a value of 3 for this method.

Whichever technique one chooses to employ, API designers should bear the following principles in mind: