Spring Boot URI Versioning

Back to: Spring Boot Tutorials

Spring Boot URI Versioning with Examples

In this article, I am going to discuss Spring Boot URI Versioning with Examples. Please read our previous article where we discussed Spring Boot Dynamic Filtering with Examples.

What is Versioning in Spring Boot?

Versioning is a crucial aspect of an API. It ensures that the API remains backward compatible, allowing for faster iteration when changes are identified. It is always recommended to version a Web API.

Imagine a situation where an API is already in production and being used by clients. The developers want to add new functionality to the API while keeping the existing functionality unchanged. This is because some users may still want to use the old version of the API while others want to take advantage of the new features. Versioning allows for this flexibility by enabling multiple versions of the API to coexist.

By implementing versioning, developers can make changes and add new features without disrupting the experience of existing users. This allows for a smoother transition and ensures that all users can continue to use the API in the way that best suits their needs. Overall, versioning is an essential tool for maintaining and improving an API over time.

When do we require Versioning in Spring Boot?

When a breaking change is made to an API, it is important to increase the version number. Breaking changes can include changes to the format or type of response data or the removal or deprecation of any part of the API.

Such changes should result in an update to the major version number of the API or content response type. This helps to clearly communicate to users that significant changes have been made. On the other hand, non-breaking changes, such as the addition of new endpoints or response parameters, do not require an update to the major version number. However, it can still be useful to track these changes by updating the minor version number of the API.

What is URI Versioning in Spring Boot?

URI versioning is a simple and straightforward approach to API versioning. It involves specifying the version number in the URL as a query parameter. However, this approach has its drawbacks. It violates the principle that a URI should refer to a unique resource and can break client integration when the version is updated.

Examples of URI versioning include

• http://api.demo.com/v1
• http://apiv1.demo.com

The version identifier does not have to be numeric or follow the v[x] syntax. Alternatives can include using a date, project name, season, or other meaningful identifier that changes with each new version.

Implementing URI Versioning in Spring Boot

Step 1: Create a new project using Spring Initializr in VS Code. Remember to add the Spring Web dependency.

Step 2: Create a new file called StudentV1.java in the src/main/java/com/dotnet/uriversioning directory. This is the first version of the POJO class.

Step 3: Add the following fields to the newly created StudentV1.java file:

Step 4: Add setters, getters, a default constructor, and a normal constructor to the StudentV1 class. Use the “Source Action…” option in the right-click menu of VS Code to do this.

Step 5: Create a new file called StudentV2.java in the src/main/java/com/dotnet/uriversioning directory. This represents the second version of the POJO class. Here, we split the name attribute into three: firstName, middleName, and lastName.

Step 6: Add the following fields to the newly created StudentV2.java file:

Step 7: Add setters, getters, a default constructor, and a normal constructor to the StudentV1 class. Use the “Source Action…” option in the right-click menu of VS Code to do this.

Step 8: Create a new file called StudentVersioningController.java in the src/main/java/com/dotnet/uriversioning directory. This represents the REST Controller class.

Step 9: Modify the newly created StudentVersioningController.java as follows:

We have performed the following modifications:

1. Imported the required packages
2. Added two functions: one which works with StudentV1.java, and another which works with StudentV2.java.

Step 10: Compile and execute the application. Ensure compilation is successful.

Step 11: Send a GET request to the URL http://localhost:8080/v1/student via Postman. You should see the following reply:

As can be seen, this returns an object of type StudentV1. We know this because the name is together (and not split into firstName, middleName, and lastName).

Step 12: Send a GET request to the URL http://localhost:8080/v2/student via Postman. You should see the following reply:

As can be seen, this returns an object of type StudentV2. We know this because the name is split into firstName, middleName, and lastName.

Congratulations! You now know how to implement URI Versioning in Spring Boot.

The Complete Example Code

StudentV1.java

package com.dotnet.uriversioning;

public class StudentV1
{
    private String name;
    private int id;
    private String email;
    public String getName()             {return name;}
    public void setName(String name)    {this.name = name;}
    public int getId()                  {return id;}
    public void setId(int id)           {this.id = id;}
    public String getEmail()            {return email;}
    public void setEmail(String email)  {this.email = email;}
    public StudentV1()                  {}
    
    public StudentV1(String name, int id, String email) {
        this.name = name;
        this.id = id;
        this.email = email;
    }
}

StudentV2.java

package com.dotnet.uriversioning;

public class StudentV2
{
    private String firstName;
    private String middleName;
    private String lastName;
    private int id;
    private String email;

    public String getFirstName()                    {return firstName;}
    public void setFirstName(String firstName)      {this.firstName = firstName;}
    public String getMiddleName()                   {return middleName;}
    public void setMiddleName(String middleName)    {this.middleName = middleName;}
    public String getLastName()                     {return lastName;}
    public void setLastName(String lastName)        {this.lastName = lastName;}
    public int getId()                              {return id;}
    public void setId(int id)                       {this.id = id;}
    public String getEmail()                        {return email;}
    public void setEmail(String email)              {this.email = email;}
    public StudentV2()                              {}
    
    public StudentV2(String firstName, String middleName, String lastName, int id, String email)
    {
        this.firstName = firstName;
        this.middleName = middleName;
        this.lastName = lastName;
        this.id = id;
        this.email = email;
    }   
}

StudentVersioningController.java

package com.dotnet.uriversioning;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class StudentVersioningController
{
    @GetMapping("/v1/student")
    public StudentV1 getStudentV1 ()
    {
        return new StudentV1("Student Number 1", 1, "student.no.1@uni.com");
    }

    @GetMapping("/v2/student")
    public StudentV2 getStudentV2 ()
    {
        return new StudentV2("Student", "Number", "1", 1, "student.no.1@uni.com");
    }
}

UriversioningApplication.java

package com.dotnet.uriversioning;

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

@SpringBootApplication
public class UriversioningApplication {

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

In the next article, I am going to discuss Spring Boot Request Parameter Versioning with Examples. Here, in this article, I try to explain Spring Boot URI Versioning with Examples. I hope you enjoy this Spring Boot URI Versioning article.