TheCodeBuzz

Today in this article, We shall see the high-level importance of enabling API Versioning in API developments and will learn RESTFul API Versioning – Best Practices.

Today in this article, we will cover the following aspects,

API Change is Constant

API change is inevitable with the new business requirements changing day-to-day. Each requirement brings multiple changes to the Resources and the resource structure keeps on changing.

While addressing every new requirement, the first important thing is that you protect your existing clients.

The second important thing is to remain flexible enough to evolve/enhance API to address the new requirements with new features and resources being exposed.

API versioning comes to the rescue to protect your API from any breaking changes or changes in resources for any new requirements more importantly without breaking any existing clients.

API Contract exist in REST API ?

This contract-based programming technique is not different from what you might have experienced while dealing with legacy using the WebService/WCF services contract.

Right from legacy services to today’s modernized API, there is always a need for contract-based programming. A contract ensures data is delivered as per agreement.

So the way your client interacts with your API is solely based on the context shared and clients have before the knowledge of these resources or media types your API exposes. So, the definition of these media types represents the contract, and the definition of message format becomes part of the contract.

Data Representation as Contract

Example :

If I am sending the below JSON response from Service A to Service B, Here Schema Employee represents a contract.

Both services need to abide by the schema format to be able to communicate the required data.

{
  "FirstName": "ABCD",
  "LastName": "TEST",
  "EmployeeId": "1111",
  "Address": {
    "State": "CA",
    "Country": "USA"
  }
}

You have service to offer and you are abiding to serve your client as per Contract

Any change in the structure of resources i.e type Employee could break existing clients.

Data format as Contract

Another aspect is the data format which clients generally rely on when sending the request.

REST supports many formats like JSON, XML, TEXT, etc.

Other reasons when it can be called breaking changes for API are as below,

1. Withdrawing of existing API
2. Renaming of APIs routes
3. Updating API methods(If logic changing the behavior)
4. Changes in Error Codes
5. Change in Fault Contracts

In the above example, we have used JSON as a data format for the exchange of information.

Don’t Break Existing clients

As highlighted above, while addressing every new requirement, you should protect your existing clients.

Any changes in API should not affect any of the existing clients. That means the existing clients should be able to continue using use the same URI and resource structure it points to.

The idea is simple, Use API versioning and release API as 1.0. ( If using URL versioning )

Evolving API – New Features/Resources

Also as highlighted above, while addressing every other new requirement, you should evolve/enhance your API to address any new requirements with new features and resources being exposed.

Example: Release new API as 2.0 (If using URL versioning),

Flexible Contract using URI

Versioning enables an API to indicate the resources that it exposes and a client application relies on HATEOS to submit the request and fetch the resources or features for a specific version.

HATEOAS – Enable Discovery of Resources

One of the prime principles behind REST is HATEOAS (Hypermedia as the Engine of Application State ).

As per this principle, the REST API should be able to give you a possible set of Resources without requiring prior knowledge of the URI scheme.

Your API system should be discoverable on its own. Your request should discover the required necessary resources.

Example – HTTP GET request should return the information necessary to find the resources related to the requested object and operations description on each of those resources using hyperlinks included in the response.

The good thing with this approach is your base URL never changes.

The changes that are existing API resources location/route can be based on the Explicit versioning in the URI or header versioning or media versioning etc.

High-level options to enable API Versioning

Let’s see the basic high-level option to enable API Versioning in the API,

• URL Versioning
• Query String Versioning
• Media/Header Versioning

URL Versioning

In this type of versioning technique, you add a version number to the URI for each resource. Existing URIs continue to operate as per contract, returning resources that conform to the original schema.

The idea is simple, Use API versioning and release API as 1.0

Release new API as 2.0

Query Versioning

In this type of versioning technique, you add a version number to the URI for each resource as a query string.

Existing URIs continue to operate as per contract, returning resources that conform to the original schema.

Header/Media Versioning

In this type of versioning technique, you add a version number to the URI for each resource as an accept header string. Accept header is preferable compared to a custom header.

Existing URIs continue to operate as per contract, returning resources that conform to the original schema.

Which among these is the best way to manage API versioning?

There are multiple ways you can achieve API versioning.

• Enable API Versioning in API

• URL API Versioning

• QueryString API Versioning

• Media/Header API Versioning

I have discussed in detail these aspects in the below article,

• How to add API Versioning in ASP.NET Core

• Header/Media API versioning in .NET

Do you have any comments or ideas or any better suggestions to share?

Please sound off your comments below.

Happy Coding !!

Please bookmark this page and share it with your friends. Please Subscribe to the blog to receive notifications on freshly published(2024) best practices and guidelines for software design and development.