Versioning RESTful Services


This guide will help you understand why versioning is needed and how you can version your REST API. We will look at 4 ways of versioning and also compare the different approaches.

You will learn

  • Why do we need Versioning for RESTful Web Services?
  • What are the versioning options that are available?
  • How do you implement Versioning for RESTful Web Services?

Image

Image

Image

Image

10 Step Reference Courses

Project Code Structure

Following screenshot shows the structure of the project we will create. Image

A few details:

  • SpringBoot2RestServiceApplication.java - The Spring Boot Application class generated with Spring Initializer. This class acts as the launching point for application.
  • pom.xml - Contains all the dependencies needed to build this project. We will use Spring Boot Starter AOP.
  • StudentV1.java - Basic Version of the Student Bean.
  • StudentV2.java - Advanced Version of the Student Bean using a seperate bean for Name.
  • Name.java - Seperate bean for Name having different parts of the Name.
  • StudentVersioningController.java - Controller from where all the service versions are exposed.

Tools you will need

  • Maven 3.0+ is your build tool
  • Your favorite IDE. We use Eclipse.
  • JDK 1.8+

Complete Maven Project With Code Examples

Our Github repository has all the code examples - https://github.com/in28minutes/spring-boot-examples/tree/master/spring-boot-2-rest-service-versioning

Why do we need to version our RESTful API?

The best approach to versioning is NOT to do it. Yeah, that’s right. Do not version as long as versioning is not needed.

Build your services to backward compatible so that you can avoid versioning as much as possible!

However there are a number of situations where versioning is needed.

Let’s consider an example.

You had this version of the student service initially

{
  "name": "Bob Charlie"
}

At a later point, you wanted to split the name up. So, you created this version of the service.

{
  "name": {
    "firstName": "Bob",
    "lastName": "Charlie"
  }
}

You can support both these requests from the same service, but it becomes complex as the requirements diversify for each of the versions.

In these kind of situations, versioning becomes mandatory.

Let’s create a simple project and understand the 4 different approaches to versioning your RESTful services.

Bootstrapping with Spring Initializr

Creating a REST service with Spring Initializr is a cake walk. We will use Spring Web MVC as our web framework.

Spring Initializr http://start.spring.io/ is great tool to bootstrap your Spring Boot projects.

Image

Image

As shown in the image above, following steps have to be done

  • Launch Spring Initializr and choose the following
    • Choose com.in28minutes.springboot.rest.example as Group
    • Choose spring-boot-2-rest-service-basic as Artifact
    • Choose following dependencies
      • Web
      • DevTools
  • Click Generate Project.
  • Import the project into Eclipse. File -> Import -> Existing Maven Project.

Implementing Beans for Versioning

First version of Bean

public class StudentV1 {
  private String name;

Second Version of Bean

public class StudentV2 {
  private Name name;

Name has firstName and lastName and is used by StudentV2

public class Name {
  private String firstName;
  private String lastName;

Versioning Approaches for RESTful Services

We would want to create two versions of services, one returning StudentV1 and the other returning StudentV2.

Let’s look at the 4 Different Approaches for creating versions of the same service.

URI Versioning

Basic approach to versioning is to create a completely different URI for the new service. Example implementation is shown below.

Examples

  • http://localhost:8080/v1/person
  • http://localhost:8080/v2/person
@RestController
public class StudentVersioningController {

  @GetMapping("v1/student")
  public StudentV1 studentV1() {
    return new StudentV1("Bob Charlie");
  }

  @GetMapping("v2/student")
  public StudentV2 studentV2() {
    return new StudentV2(new Name("Bob", "Charlie"));
  }

http://localhost:8080/v1/person

Response

{
  "name": "Bob Charlie"
}

http://localhost:8080/v2/person

Response

{
  "name": {
    "firstName": "Bob",
    "lastName": "Charlie"
  }
}

Request Parameter versioning

Next approach to versioning is to use the request parameter to differentiate versions.

Examples

  • http://localhost:8080/person/param?version=1
  • http://localhost:8080/person/param?version=2

Implementations are shown below:

  @GetMapping(value = "/student/param", params = "version=1")
  public StudentV1 paramV1() {
    return new StudentV1("Bob Charlie");
  }

  @GetMapping(value = "/student/param", params = "version=2")
  public StudentV2 paramV2() {
    return new StudentV2(new Name("Bob", "Charlie"));
  }

http://localhost:8080/person/param?version=1

Response

{
  "name": "Bob Charlie"
}

http://localhost:8080/person/param?version=2 Response

{
  "name": {
    "firstName": "Bob",
    "lastName": "Charlie"
  }
}

(Custom) Headers versioning

The third approach to versioning is to use a Request Header to differentiate the versions.

Examples

  • http://localhost:8080/person/header
    • headers=[X-API-VERSION=1]
  • http://localhost:8080/person/header
    • headers=[X-API-VERSION=2]

Implementations are shown below:

  @GetMapping(value = "/student/header", headers = "X-API-VERSION=1")
  public StudentV1 headerV1() {
    return new StudentV1("Bob Charlie");
  }

  @GetMapping(value = "/student/header", headers = "X-API-VERSION=2")
  public StudentV2 headerV2() {
    return new StudentV2(new Name("Bob", "Charlie"));
  }

Below picture shows how we can execute a Get Request Method with Request Headers using Postman. Image

http://localhost:8080/person/header with a header

  • X-API-VERSION=1

Response

{
  "name": "Bob Charlie"
}

http://localhost:8080/person/header with a header

  • X-API-VERSION=2

Response

{
  "name": {
    "firstName": "Bob",
    "lastName": "Charlie"
  }
}

Media type versioning (a.k.a “content negotiation” or “accept header”)

The last versioning approach is to use the Accept Header in the request.

Examples

  • http://localhost:8080/person/produces
    • headers[Accept=application/vnd.company.app-v1+json]
  • http://localhost:8080/person/produces
    • headers[Accept=application/vnd.company.app-v2+json]
  @GetMapping(value = "/student/produces", produces = "application/vnd.company.app-v1+json")
  public StudentV1 producesV1() {
    return new StudentV1("Bob Charlie");
  }

  @GetMapping(value = "/student/produces", produces = "application/vnd.company.app-v2+json")
  public StudentV2 producesV2() {
    return new StudentV2(new Name("Bob", "Charlie"));
  }

Below picture shows how we can execute a Get Request Method with Request Headers using Postman. Image

http://localhost:8080/person/produces with a header

  • Accept=application/vnd.company.app-v1+json Response
    {
    "name": "Bob Charlie"
    }
    

http://localhost:8080/person/produces with a header

  • Accept=application/vnd.company.app-v2+json

Response

{
  "name": {
    "firstName": "Bob",
    "lastName": "Charlie"
  }
}

Factors affecting Versioning Choice

Following factors affect the choice of versioning:

  • URI Pollution - URL versions and Request Param versioning pollute the URI space.
  • Misuse of HTTP Headers - Accept Header is not designed to be used for versioning.
  • Caching - If you use Header based versioning, we cannot cache just based on the URL. You would need take the specific header into consideration.
  • Can we execute the request on the browser? - If you have non technical consumers, then the URL based version would be easier to use as they can be executed directly on the browser.
  • API Documentation - How do you get your documentation generation to understand that two different urls are versions of the same service?

The fact is that there is No Perfect Solution for versioning.

The list below shows Major API providers using different versioning approaches.

  • Media type versioning (a.k.a “content negotiation” or “accept header”)
    • GitHub
  • (Custom) Headers versioning
    • Microsoft
  • URI Versioning
    • Twitter
  • Request Parameter versioning
    • Amazon

Plan to avoid versioning as far as possible but evaluate and be ready with a versioing strategy before you expose your first service to your consumer. Good Luck!

More Reading

  • https://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown
  • http://urthen.github.io/2013/05/09/ways-to-version-your-api/
  • http://stackoverflow.com/questions/389169/best-practices-for-api-versioning
  • http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/
  • https://www.3scale.net/2016/06/api-versioning-methods-a-brief-reference/

Next Steps

Image

Image

Image

Image

Image

Image

Image

Image

Image

Complete Code Example

/pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.in28minutes.springboot.rest.example</groupId>
  <artifactId>spring-boot-2-rest-service-versioning</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <packaging>jar</packaging>

  <name>spring-boot-2-rest-service</name>
  <description>Spring Boot 2 and REST - Example Project</description>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.0.0.RELEASE</version>
    <relativePath/> <!-- lookup parent from repository -->
  </parent>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <java.version>1.8</java.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-devtools</artifactId>
      <scope>runtime</scope>
    </dependency>
    <dependency>
      <groupId>com.h2database</groupId>
      <artifactId>h2</artifactId>
      <scope>runtime</scope>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>

  <repositories>
    <repository>
      <id>spring-snapshots</id>
      <name>Spring Snapshots</name>
      <url>https://repo.spring.io/snapshot</url>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
    <repository>
      <id>spring-milestones</id>
      <name>Spring Milestones</name>
      <url>https://repo.spring.io/milestone</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
  </repositories>

  <pluginRepositories>
    <pluginRepository>
      <id>spring-snapshots</id>
      <name>Spring Snapshots</name>
      <url>https://repo.spring.io/snapshot</url>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </pluginRepository>
    <pluginRepository>
      <id>spring-milestones</id>
      <name>Spring Milestones</name>
      <url>https://repo.spring.io/milestone</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </pluginRepository>
  </pluginRepositories>


</project>

/src/main/java/com/in28minutes/springboot/rest/example/SpringBoot2RestServiceApplication.java

package com.in28minutes.springboot.rest.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringBoot2RestServiceApplication {

  public static void main(String[] args) {
    SpringApplication.run(SpringBoot2RestServiceApplication.class, args);
  }
}

/src/main/java/com/in28minutes/springboot/rest/example/versioning/Name.java

package com.in28minutes.springboot.rest.example.versioning;
public class Name {
  private String firstName;
  private String lastName;

  public Name() {
  }

  public Name(String firstName, String lastName) {
    super();
    this.firstName = firstName;
    this.lastName = lastName;
  }

  public String getFirstName() {
    return firstName;
  }

  public void setFirstName(String firstName) {
    this.firstName = firstName;
  }

  public String getLastName() {
    return lastName;
  }

  public void setLastName(String lastName) {
    this.lastName = lastName;
  }

}

/src/main/java/com/in28minutes/springboot/rest/example/versioning/StudentV1.java

package com.in28minutes.springboot.rest.example.versioning;
public class StudentV1 {
  private String name;

  public StudentV1() {
    super();
  }
  
  public StudentV1(String name) {
    super();
    this.name = name;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  
}

/src/main/java/com/in28minutes/springboot/rest/example/versioning/StudentV2.java

package com.in28minutes.springboot.rest.example.versioning;
public class StudentV2 {
  private Name name;

  public StudentV2() {
    super();
  }

  public StudentV2(Name name) {
    super();
    this.name = name;
  }

  public Name getName() {
    return name;
  }

  public void setName(Name name) {
    this.name = name;
  }

}

/src/main/java/com/in28minutes/springboot/rest/example/versioning/StudentVersioningController.java

package com.in28minutes.springboot.rest.example.versioning;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class StudentVersioningController {

  @GetMapping("v1/student")
  public StudentV1 studentV1() {
    return new StudentV1("Bob Charlie");
  }

  @GetMapping("v2/student")
  public StudentV2 studentV2() {
    return new StudentV2(new Name("Bob", "Charlie"));
  }

  @GetMapping(value = "/student/param", params = "version=1")
  public StudentV1 paramV1() {
    return new StudentV1("Bob Charlie");
  }

  @GetMapping(value = "/student/param", params = "version=2")
  public StudentV2 paramV2() {
    return new StudentV2(new Name("Bob", "Charlie"));
  }

  @GetMapping(value = "/student/header", headers = "X-API-VERSION=1")
  public StudentV1 headerV1() {
    return new StudentV1("Bob Charlie");
  }

  @GetMapping(value = "/student/header", headers = "X-API-VERSION=2")
  public StudentV2 headerV2() {
    return new StudentV2(new Name("Bob", "Charlie"));
  }

  @GetMapping(value = "/student/produces", produces = "application/vnd.company.app-v1+json")
  public StudentV1 producesV1() {
    return new StudentV1("Bob Charlie");
  }

  @GetMapping(value = "/student/produces", produces = "application/vnd.company.app-v2+json")
  public StudentV2 producesV2() {
    return new StudentV2(new Name("Bob", "Charlie"));
  }

}

/src/main/resources/application.properties


/src/test/java/com/in28minutes/springboot/rest/example/SpringBoot2RestServiceApplicationTests.java

package com.in28minutes.springboot.rest.example;

import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;

@RunWith(SpringRunner.class)
@SpringBootTest
public class SpringBoot2RestServiceApplicationTests {

  @Test
  public void contextLoads() {
  }

}

Related Posts

Spring Boot Tutorials for Beginners

At in28Minutes, we are creating a number of tutorials with videos, articles & courses on Spring Boot for Beginners and Experienced Developers. This resources will help you learn and gain expertise at Spring Boot.

Introduction To Aspect Oriented Programming and Cross Cutting Concerns

Software applications are built in layers. There is common functionality that is sometimes needed across layers - logging, performance tracing etc. How do you implement these common features?

Programming Basics - Introduction To Object Oriented Programming

Object oriented programming (OOP) is all about thinking in terms of objects. Let's dig deeper.

Programming Basics - Five Things To Think About While Programming

You would obviously want to write code that meets your core requirements and provide good performance - choosing right data structures and algorithms to use is the fundamental part of programming. What are the other things that you need to worry about? Here are five things that we think are essential.

Asynchronous communication with queues and microservices - A perfect combination?

In this article, we throw some light on what asynchronous messaging is all about and discuss why you should consider it for your microservices architectures.

Microservice Best Practice - Build an Archetype

In this article, we focus on learning why creating proper archetypes is important for successful microservices architecture.

Microservice Architecture Best Practices - Messaging Queues

In this article, we discuss why Messaging queues are needed, and how they form the cornerstone of communication in microservices architectures.

Microservice Best Practice - Why do you build a Vertical Slice?

In this article, we look at what is a vertical slice, and why we build it. We also discuss the best practices involved in building vertical slices.

Microservices Architectures - Event Driven Approach

In this article, we talk about event driven approach, in the context of microservices architectures. We also discuss what are the advantages of using an event driven approach.

The 12 Factor App - Best Practices In Cloud Native Applications and Microservices

In order that an application be deployed in the cloud and enjoy features such as auto scaling, it first needs to be cloud native. In this article, we have a close look at the best practices for cloud native applications, popularly known as The 12 Factor App.