Part 4 – Spring Rest Versioning

November 11, 2018 Saurabh Oza Spring Framework, Spring Rest 0

Spring Rest Versioning

What have we learned so far,

Part 1 – Spring Rest Advance : Input / Bean Validations In this post, we discussed the steps to validate the input bean in Spring Rest.
Part 2 – Spring Rest Advance : Rest Documentation with Swagger 2 In this post, we discussed the steps to configure swagger to do the documentation for Spring Rest services
Part 3 – Spring Rest Advance : Spring Boot with H2 DB In this post, we discussed the steps to configure and use H2 db in spring boot
version

What is Rest API Versioning ?

When we want to add extra functionality to the existing exposed api then we go for versioning of that api to provide new functionality. Suppose we have exposed the api to get the details of Employee with http://www.xyz.com/employees . After three months we have added new functionality to this GET api to get the details of the associated project with employee details. Now we need to do the versioning of this new release so that we can provide new functionality to new users as well as backword compatibility to existing users. Most popular giants like Facebook, Twitter, Netflix are versioning their APIs. The need of versioning the Rest API is to give extra functionality to your existing system. In this post we will discuss the different ways of versioning. There are some different ways to provide an API versioning in your application. The most popular of them are though :

Different types of Spring Rest Versioning ?

1. URI Path / Path Param – you include the version number in the URL path of the endpoint, for example /v1/students 2. Query Parameters – you pass the version number as a query parameter with specified name, for example / students?version=1 3. Custom HTTP Headers – you define a new header that contains the version number in the request 4. Content Negotiation – the version number is included to the “Accept” header together with accepted content type.

1. URI Path / Path Param versioning in Spring Rest

In this technique we use URI Param / Path Param to create the versioning of REST APIs. Here /v1 will be the version of our rest api. in /v1 we are sending the fullName to the users and in /v2 we are sending the firstName and laastName to the user. 
@RestController
public class StudentVersioningController {

 @GetMapping("/v1/students")
 public StudentV1 studentV1() {
  return new StudentV1("Saurabh Oza");
 }

 @GetMapping("/v2/students")
 public StudentV2 studentV2() {
  return new StudentV2("Saurabh", "Oza");
 }
}
Output : http://localhost:8080/v1/students { “fullName”: “Saurabh Oza” } http://localhost:8080/v2/students { “firstName”: “Saurabh”, “lastName”: “Oza” }

2. Query Parameters versioning in Spring Rest

In this technique we use URI Param / Path Param to create the versioning of REST APIs. 
@RestController
public class StudentVersioningController {

 @GetMapping(value = "/students" , params="version=1")
 public StudentV1 studentV1WithQueryParam() {
  return new StudentV1("Saurabh Oza");
 }

 @GetMapping(value = "/students" , params="version=2")
 public StudentV2 studentV2WithQueryParam() {
  return new StudentV2("Saurabh", "Oza");
 }
}
Output : http://localhost:8080/students?version=1 { “fullName”: “Saurabh Oza” } http://localhost:8080/students?version=2 { “firstName”: “Saurabh”, “lastName”: “Oza” }

3. Custom HTTP Headers versioning in Spring Rest

In this technique we pass custom header in the request to create the versioning of API. 
@RestController
public class StudentVersioningController {

 @GetMapping(value = "/students" , headers="version=1")
 public StudentV1 studentV1WithHeader() {
  return new StudentV1("Saurabh Oza");
 }

 @GetMapping(value = "/students" , headers="version=2")
 public StudentV2 studentV2WithHeader() {
  return new StudentV2("Saurabh", "Oza");
 }
}
Output : Go to postman and add header as version with value as 1 and press hit Version 1 Version 2

4. Content Negotiation versioning in Spring Rest

In this technique we pass Accept header in the request to create the versioning of API. 
@RestController
public class StudentVersioningController {

 @GetMapping(value = "/students" , produces="application/onlyfullstack.app-v1+json")
 public StudentV1 studentV1WithContentType() {
  return new StudentV1("Saurabh Oza");
 }

 @GetMapping(value = "/students" , produces="application/onlyfullstack.app-v2+json")
 public StudentV2 studentV2WithContentType() {
  return new StudentV2("Saurabh", "Oza");
 }
}
Output: Version 3 Version 4

Source Code

Download source code of Spring Rest Advance Topics from below git repository : spring-rest-advance-topics

Spring Rest Advanced Tutorial

https://www.onlyfullstack.com/spring-rest-advanced-tutorial/

Lets go to our next tutorial where we will discuss below point

5. Asynchronous Spring Service With @Async And @EnableAsync
– How To Do @Async in Spring Service
– What is the need of Asynchronous?
– How to use @Async and @EnableAsync in Spring Boot
Blog URL – Part 5 – Asynchronous Spring Service With @Async And @EnableAsync