Versioning RESTful Web Services-Basic Approach With URIs

Versioning Approaches

These are the following approaches from which we can choose one to apply API versioning. And we will be using spring-boot examples to implement them.

1. URI versioning
2. Custom Request Header versioning
3. Accept Header versioning
4. Parameter versioning

URI Versioning

With the help of URI, we can implement API versioning. URI stands for Uniform Resource Identifier, a sequence or collection of characters to identify a location of a particular web resource. Example: http://URIversioningExample.com/api/profile,

How to Implement URI Versioning?

To implement URI versioning, an example is given below:

This is the first version of the product class. And this class only has a product name to display, and we need to show the price too for the product so that we will create a different version.

public class ProductVer1
{
   private String productname;
}

You can also try this code with Online Java Compiler

Run Code

The second version of the product class

public class ProductVer2
{
    private NamePrice detail;
}

You can also try this code with Online Java Compiler

Run Code

NamePrice class contains product name and price for version2

public class NamePrice
{
    privarte String productname;
    private  String price;
}

You can also try this code with Online Java Compiler

Run Code

Product versioning control class to call and display the different versions.

import org.springframework.web.bind.annotation.GetMapping;  
import org.springframework.web.bind.annotation.RestController;  
@RestController
public class ProductVersioningController {

//intializing URI using GetMapping method
  @GetMapping("ver1/product")
// calling productVer1
  public ProductVer1 productVer1() {
    return new ProductVer1("Deodorant");
  }

//intializing URI using GetMapping method
  @GetMapping("ver2/product")
  // calling productVer2
  public ProductVer2 productVer2() {
    return new productVer2(new NamePrice("Deodorant", "120-rupees"));
  }

You can also try this code with Online Java Compiler

Run Code

http:/localhost:5000/ver1/product

http:/localhost:5000/ver2/product

The above URLs will be used to call the product functions in JSON format.

Version1:

Version2:

Accept Header Versioning

Another way to version APIs is to accept an HTTP header. By using accept Header, we do not need to mention the API version in the URI; instead, we can just integrate an Accept Header with API, which contains information about the API's application type and output format. This method is also called content negotiation. It is difficult to access as compared to URI versioning.

Example

We will use produce to initialize the Accept Header with media type and versioning for Accept Header.

import org.springframework.web.bind.annotation.GetMapping;  
import org.springframework.web.bind.annotation.RestController;  
@RestController
public class ProductVersioningController {

//initialize accept header using GetMapping method
@GetMapping(value = "/product/produces", produces = "application/vnd.codingninja.app-v1+json")

// calling productVer1
  public ProductVer1 productVer1() {
    return new ProductVer1("Deodorant");
  }

//initialize accept header using GetMapping method
@GetMapping(value = "/product/produces", produces = "application/vnd.codingninja.app-v1+json")

  // calling productVer2
  public ProductVer2 productVer2() {
    return new productVer2(new NamePrice("Deodorant", "120-rupees"));
 }

You can also try this code with Online Java Compiler

Run Code

Custom HTTP Header Versioning

The custom HTTP header method is also similar to the content negotiation method. In this, we need to create a request header with a relevant name and version number as an attribute to differentiate. We do not need to change the whole URI in this method.

Example

In the custom HTTP header methods, we need to initialize a header with a relevant name and attribute as a version number.

import org.springframework.web.bind.annotation.GetMapping;  
import org.springframework.web.bind.annotation.RestController;  
@RestController
public class ProductVersioningController {

//initialize custom header using GetMapping method
 @GetMapping(value = "/product/header", headers = "CurrentAPI-VERSION=1")

// calling productVer1
  public ProductVer1 productVer1() {
    return new ProductVer1("Deodorant");
  }

//initialize custom header using GetMapping method
 @GetMapping(value = "/product/header", headers = "CurrentAPI-VERSION=2")

  // calling productVer2
  public ProductVer2 productVer2() {
    return new productVer2(new NamePrice("Deodorant", "120-rupees"));
 }

You can also try this code with Online Java Compiler

Run Code

Parameter Versioning

In the parameter versioning, you must set a parameter in the URI as the API version number. You will only locate the resource integrated with the particular param.

Example

import org.springframework.web.bind.annotation.GetMapping;  
import org.springframework.web.bind.annotation.RestController;  
@RestController
public class ProductVersioningController {

//initialize params using the GetMapping method
 @GetMapping(value = "/product/param", params = "version=1")

// calling productVer1
  public ProductVer1 productVer1() {
    return new ProductVer1("Deodorant");
  }

//initialize params using the GetMapping method
 @GetMapping(value = "/product/param", params = "version=2")

  // calling productVer2
  public ProductVer2 productVer2() {
    return new productVer2(new NamePrice("Deodorant", "120-rupees"));
 }

You can also try this code with Online Java Compiler

Run Code

Version1:

Version2:

Frequently Asked Questions

Can we apply API versioning if we remove any functionality from an API?

If you remove functionality, you are changing the API features; you must apply API versioning here.

Can we accept the header method in a browser? 

Accept Header method is less accessible than URI versioning; you will need a plugin to implement this method.

Is custom header and accept header are same?

No, they are not the same but similar to an extent.

What are some of the breaking changes to version an API?

Breaking changes like adding new functionality, changing the data format, and many more.

How to implement post requests in springboot?

You have to use the @PostMapping method to implement a post request at a URL.

Conclusion

In this blog, we discussed the need for API versioning and the different methods like URI versioning, Custom Header, Accept Header, and Params. We discussed all the methods with examples.

To learn more about RESTful web services, check out the following articles.

• Introduction to RESTful Web Service
• RESTful - Resources
• RESTful - Environment setup
• RESTful - Application

To learn more about DSA, competitive coding, and many more knowledgeable topics, please look into the guided paths on Coding Ninjas Studio. Also, you can enroll in our courses and check out the mock test and problems available to you. Please check out our interview experiences and interview bundle for placement preparations.

Happy Learning!