REST API Versionin

#restversioning #restapi

What is Semantic Versioning 2.0.0 ?

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes
2. MINOR version when you add functionality in a backwards compatible manner
3. PATCH version when you make backwards compatible bug fixes

Why do we need API versioning ?

One of the major challent5ges surrounding exposing services is handling updates to the API contract :

1. Clients may not want to update their applications when the API changes.
2. Clients continue using the existing REST API and migrate their applications to the newer API when they are ready.
3. it ensures stability and reliability. If you don't properly version APIs, it can have disastrous effects on downstream products and services.

What are the possible the breaking changes ?

1. Changing the request/response format (e.g. from XML to JSON)
2. Changing a property name (e.g. from name to productName) or data type on a property (e.g. from an integer to a float)
3. Adding a required field on the request (e.g. a new required header or property in a request body)
4. Removing a property on the response (e.g. removing description from a product)

What are Effective change management principles ?

• Continue support for existing properties/endpoints
• Add new properties/endpoints rather than changing existing ones
• Thoughtfully sunset obsolete properties/endpoints

4 REST API Versioning Strategies :

1. Versioning through URI Path : http://hostname/v1/investors

This solution often uses URI routing to point to a specific version of the API. you may consider API gateways.When a new version of the REST API is released, it is perceived as a new entry in the cache.

• Pros: Clients can cache resources easily
• Cons: This solution has a pretty big footprint in the code base as introducing breaking changes implies branching the entire API

Note : The major and minor version changes can be a part of the URI

@GetMapping({"/v1/investors","/v1.1/investors","/v2/investors"})

public List<Investor> fetchAllInvestors()
{
       return investorService.fetchAllInvestors();
}        

2. Versioning through query parameters : http://hostname/investors?version=2.0

• Pros: It’s a straightforward way to version an API, and it’s easy to default to the latest version
• Cons: Query parameters are more difficult to use for routing requests to the proper API version

@GetMapping("/investors")

public List<Investor> fetchAllInvestorsForGivenVersionAsParameter(
@RequestParam("version") String version)

throws VersionNotSupportedException {

      if (!(version.equals("1.1") || version.equals("1.0"))) {
             throw new VersionNotSupportedException("version " + version);
       }

      return investorService.fetchAllInvestors();
})        

3. Versioning through custom headers

curl -H “x-source-version: 2.0” http://hostname/investors

• Pros: It doesn’t clutter the URI with versioning information
• Cons: It requires custom headers

@GetMapping("/investorsbycustomheaderversion"

public List<Investor> fetchAllInvestors...(
@RequestHeader("x-resource-version") String version)

throws VersionNotSupportedException {

        return getResultsAccordingToVersion(version);
})        

4. Versioning through content negotiation

curl -H “Accept: application/investors-v1.1+json” http://hostname/investors

• Pros: Allows us to version a single resource representation instead of versioning the entire API, Createing a smaller footprint. Doesn’t require implementing URI routing rules.
• Cons: Requiring HTTP headers with media types makes it more difficult to test and explore the API using a browser

@GetMapping(value = "/investorsbyacceptheader"

headers = "Accept=application/investors-v1+json,
application/investors-v1.1+json")

public List<Investor> fetchAllInvestorsForGiven..()
throws VersionNotSupportedException {

     return getResultsAccordingToVersion("1.1");
}        

Then response header content-type= Accept=application/investors-v1+json

PLEASE NOTE : You can use the URL path versioning with the major and include the complete version in the request using custom headers.

Refrences :

[1] https://www.xmatters.com/blog/blog-four-rest-api-versioning-strategies/

[2] https://semver.org/

[3] O'rielly : Hands-On RESTful API Design Patterns and Best Practices

[4] https://www.freecodecamp.org/news/how-to-version-a-rest-api/