What is versioning all about?

I found the name "versioning" in an article I read not long ago. The article talked about best practices when creating a REST API. I assume we are all tech-savvy here😉 but for those who aren't find below the Wikipedia version of what a REST API is

A REST API (also known as a "RESTful API") is an application programming interface (API or web API) that conforms to the constraints of the REST architectural style and allows for interaction with RESTful web services.

Quite cumbersome if you would agree… In simpler terms, a REST API is a way for two computer systems to communicate with each other over the internet. It stands for "Representational State Transfer" and is a set of rules for how the systems should send data back and forth to each other.

Imagine you are trying to get a glass of water from the kitchen. You would go to the kitchen and ask someone to give you a glass of water. They would then get a glass and fill it with water from the tap before giving it to you. In this situation, you are like a computer system, and the person in the kitchen is like another computer system. You are sending a request for a glass of water, and the other system is responding by giving you the water.

A REST API works in a similar way. One system (like a website) can send a request to another system (like a server) and ask it to do something, like get some data or save some information. The second system will then do what was asked and send a response back to the first system with the result.

Does that make sense?

Let’s try not to stray too much from the topic. Like any good developer, I searched Google for the ambiguous term at hand and discovered that I had already been using “versioning” in some of my projects; however, I hadn't given it much thought at the time or had chosen to use it because I saw others using it in their code. (p.s. : If there is a term you don't seem to understand, try searching for it before implementing.)

What is versioning ❓

"Versioning" refers to the technique of making different versions of a web API available and accessible to developers. This enables the API to adapt and expand over time while remaining backward-compatible with existing integrations.

There are several standard techniques for API versioning. One common approach is to include the API's version number in the base URL. For instance, an API might have a base URL of "https://api.example.com/v1" for version 1 and "https://api.example.com/v2" for version 2. A developer only needs to use the correct base URL to use a certain version of the API.

Another common approach is to utilize the HTTP request's Accept header to identify the version of the API that the client wants to use. The server will then respond with the appropriate version of the API.

To elaborate on the techniques I briefly mentioned above, there are four common approaches you might take when versioning.

1. URI Path Versioning

2. URL Parameter Versioning

3. Versioning with Content-Type in Accept Header

4. Versioning with Custom Header

URI Path Versioning

In URI path versioning, the version of the API is included in the URL path. For example, an API might have a base URL https://api.example.com/v1 for version 1, and a base URL https://api.example.com/v2 for version 2. When a developer wants to use a specific version of the API, they just need to use the corresponding base URL.

Here is an example of making a request to version 1 of an API using URI path versioning

fetch('https://api.example.com/v1/endpoint')
  .then(response => response.json())
  .then(data => console.log(data));

URL Parameter Versioning

In URL parameter versioning, the version of the API is included as a query parameter in the URL. For example, an API might have a base URL of https://api.example.com and the version could be specified using a version query parameter, like https://api.example.com?version=1.

Here is an example of making a request to version 1 of an API using URL parameter versioning

const params = {
  version: 1
}
fetch('https://api.example.com/endpoint', { params })
  .then(response => response.json())
  .then(data => console.log(data));

Versioning with Content-Type in Accept Header

In this approach, the version of the API is specified using the Accept header of the HTTP request. The server will then return the appropriate version of the API in the response.

Here is an example of making a request to version 1 of an API using the Accept header

const headers = {
  Accept: 'application/app.v1.categories'
}
fetch('https://api.example.com/endpoint', { headers })
  .then(response => response.json())
  .then(data => console.log(data));

Versioning with Custom Header

In this approach, a custom header is used to specify the version of the API that the client wants to use. The server will then return the appropriate version of the API in the response.

Here is an example of making a request to version 1 of an API using a custom header

const headers = {
  'X-API-Version': 1
}
fetch('https://api.example.com/endpoint', { headers })
  .then(response => response.json())
  .then(data => console.log(data));

To use this approach, the server will need to be configured to look for the custom header and return the appropriate version of the API based on the value of the header.

This approach can be useful if the API needs to support multiple versions and the other approaches (such as URI path versioning or URL parameter versioning) are not suitable.

Why is versioning important ❓

Versioning is important because it allows an API to change and evolve over time without breaking existing integrations. When a client (such as a website or mobile app) integrates with an API, it usually depends on the API to function properly. If the API changes in a way that is not backward-compatible, it can break the client's integration and cause the client to stop working.

Versioning helps to prevent this problem by allowing multiple versions of the API to exist and be used concurrently. This means that when a new version of the API is released, existing clients can continue to use the old version until they are able to update their integration to use the new version.

Versioning is also important because it allows developers to understand the changes that have been made to the API over time. By clearly documenting the changes made in each version of the API, developers can more easily understand how to use the latest version of the API and how it differs from previous versions.

Overall, versioning helps to ensure that an API can change and improve over time without causing problems for existing clients.

Best practices to remember 🤔💭

There are a few best practices to keep in mind when versioning an API:

• Use versioning to make backward-compatible changes to the API. If you need to make breaking changes, create a new version of the API rather than changing the existing version.

• Make it easy for developers to discover and use the latest version of the API.

• Clearly document the changes made in each version of the API.

Note : It's crucial to thoroughly outline the changes made in each API version so that developers may understand how the most recent version differs from earlier versions and choose which version to use.

When not to use versioning ❌✋

There are a few situations when it might not be necessary to use versioning in an API:

• If the API is still in the early stages of development and is not yet being used by any external clients, versioning may not be necessary.

• If the API is not expected to change significantly over time, versioning may not be necessary.

• If the API is intended to be used by a small group of developers who are able to quickly update their integrations in response to changes, versioning may not be necessary.

That being said, it's generally a good idea to version an API from the start, even if it's not expected to change much. This allows the API to evolve over time without breaking existing integrations. It's easier to add versioning from the beginning than it is to retroactively add it later on.

Conclusion ✍🏽🚶🏽

In the preceding article, you learned why versioning is an important technique while developing and maintaining a REST API, approaches to versioning, the value of versioning, when not to use versioning, and so on. It's crucial to choose the appropriate approach for your API and to fully outline the changes made in each API version to improve developers experience.

I'd love to receive feedback of any kind. If there's anything you'd like to tell me don't hesitate to reach out. Thanks for reading!