Versioning

Versioning is the creation and management of multiple product releases. That means the general function of the product remains the same with some improvement, upgradation, or customization.
While many developers and vendors commonly use the term in different contexts, it is often applied to operating systems, software artifacts, and web services.

API versioning is the practice of transparently managing changes to an API. Versioning is effective communication around changes to an API, so that the consumers would know what exactly to expect from that API.

Why is Versioning Important

With so many developers depending on a stable version of the service, making changes to an API could quickly raise issues. With traditional software, bugs are usually fixed between versions. However, API’s designers often don’t have that luxury. API versioning is how you deal with this contradiction. A proper API versioning strategy ensures an API version remains functional when these changes are enacted on the code. It also means that API consumers using older versions of the API won’t experience any breaking change.

We update the API major version whenever we introduce breaking changes. Internally, we update minor and patch versions whenever we add functionality and backward-compatible updates. When we release a new major version of the REST API, clients can choose to continue using an existing major version or migrate to the new one.

A versioning strategy allows clients to continue using the existing REST API and migrate their applications to the newer API when they are ready.

For example, unique names or specific numerical identifiers can be assigned to an ongoing series of product releases, such as TV-1930 to TV-2022, Internet Explorer 1995 – 2015 onwards.

• The numbers represent different versions of the same software or application, and the numbers assigned increase to correspond to the latest development and releases.

• Subsequent releases of the same product can also be assigned numerical identifiers consisting of two or three numbers separated by periods.
• The first number, called the major number, is increased when there are significant improvements or changes in functionality.

For example, when Microsoft upgraded its erstwhile Internet Explorer 4 browser to Internet Explorer 5.
The second number, called the minor number, is incremented when there are minor feature changes or notable fixes.

• Internet Explorer 5.2 indicates that minor changes were made to the earlier version, Internet Explorer 5.1.

• The third number, if it exists, is called the revision number and is added or increased when minor bugs are eliminated.

• For example, the 7 in Internet Explorer 5.1.7 shows that bug fixes were made to the previous version.

When to version an API

There is a need to update the model and provide a better versioning of APIs to the client/users/customers but at the same time it is very necessary to keep the older version APIs intact without breaking it.
That’s why it is important to support both the version of the APIs(New and Old)

API versioning should occur only when the following changes are done:

1. Change fields or routing after an API is released.
2. Change payload structures, such as changing a variable from an integer to float, for instance.
3. Remove endpoints to fix design or poor implementation of HTTP.

There are four strategies for to version of a REST API.

1. URI Path

URI is the most commonly used approach. In this way of versioning, we include the version number in the URI path like Facebook, Twitter, and many more. We are including the version of the API in the URL path.

Ex: http://localhost:5000/apisetu/v1/client

If there is a similar advanced version for this API URL will be like that.

Ex: http://localhost:5000/apisetu/v2/client

2. URL Query parameters

Another similar option for versioning a REST API is to include the version number as a query parameter. The movement when in URI we put a question mark becomes a string query parameter, so after the question mark, we have a key-value pair that is URI query parameters.

Ex: http://localhost:5000/apisetu/client?v=1.2

3. Custom Headers

REST APIs can also be versioned by providing custom headers with the version number included as an attribute, rather than you putting it URL or any content type, we have a separate custom header that we can use just called x-App-version. We can specify here what API version you want here.

Ex: GET http://localhost:5000/apisetu/v2/client/1

     x-App-version: 1.0

Instead of the version number, we can use the version date as well.

Ex: GET http://localhost:5000/apisetu/v2/client/1
    x-App-version: 2022-10-20

It is a good practice to use both dates and version numbers together.

4. Request Header

This approach allows us to version a single resource representation instead of versioning the entire API which gives us more granular control over versioning. It also creates a smaller footprint in the code base as we don’t have to fork the entire application when creating a new version. Another advantage of this approach is that it doesn’t require implementing URI routing rules introduced by versioning through the URI path.

Ex: http://localhost:5000/apisetu/v1/client

  Accept: application/app.v1.client

  Accept: application/app.v2.client

So probably say that application/app.v1.client and application/app.v2.client indicate that we need versions v1 and v2 here.

When Not To Version an API

As we’ve seen, API versioning can be a lot of work. It also raises the risk of breaking an API for the existing customers and API consumers. Sometimes it’s best to avoid creating a new API version if possible.

As a general rule of thumb, it’s best to avoid creating a whole new version unless there are changes that would break the API for the existing users.

For example, adding additional info to the user category:

{
    "user": {
        "name": "John Doe", 
        "amount": "100"
    }
}

This change would not break the API for the existing customers, so a new version would not be necessary.

Now consider this alternate example in which a new media type is specified:

GET /users/3 HTTP/1.1
Accept: application/vnd.myname.v2+json
<===
HTTP/1.1 200 OK
Content-Type: application/vnd.myname.v2+json
{
    "user": {
        "firstname": "John", 
        "lastname": "Doe", 
        "amount": "100"
    }
}

This adds even more detail to an existing URI. It also could indicate a change that could break the API for existing users, as they’ll need to understand the new media type and the accompanying semantics. It doesn’t create the need for a whole new URI, though, meaning a completely new version may not be necessary.

Finally, even major structural changes may not necessarily indicate the need for API versioning. Changing the state of representation or mirroring a Resource requires a significant overhaul of how a client interacts with an API. It doesn’t necessarily need a new version, though.

Reference:

1. https://www.xmatters.com/blog/blog-four-rest-api-versioning-strategies/
2. https://nordicapis.com/everything-you-need-to-know-about-api-versioning/