Saltar al contenido

Everything you need to know about controlling the API version

Everything you need to know about controlling the API version

APIs exist in a strange duality. On the one hand, create a digital product that software developers can incorporate. However, their product is both the data itself and access to it. With so many developers relying on a stable version of the service, changing an API could quickly lead to problems. With traditional software, bugs are generally fixed between versions. However, in the case of APIs, designers often do not afford.

API version control it is the way to deal with this contradiction. An appropriate API version control strategy ensures that an API version remains functional when code changes are made. It also means that API consumers who use earlier versions of the API will not experience any major change . By effectively communicating the change, consumers have enough time to update their integrations accordingly.

We have created a guide for controlling API versions. We’ll show you how API designers can create versions of their APIs and give some examples of why controlling API versions is a good idea. We will also see when controlling the API version Is not a good idea!

When to create an API version

In general, it is quite short and dry When to create a new version of the API – change the API at any time. However, there is more than that.

Specifically, the API version should occur whenever:

  • Change fields or routing after publishing an API.
  • Change payload structures, such as changing a variable from an integer to a float, for example.
  • Remove endpoints to correct poor HTTP design or implementation.

If you need to change any of these after your API has already been released, it may be time to release a new API version. This way, your existing customers’ digital products will not be interrupted or interrupted.

There may be other reasons why you might want to create an API version; for example, it could add endpoints or new parameters to answers needs revision . However, these changes may not warrant a completely new version. A small update may be sufficient. Regardless, following minor revisions could help address a customer’s technical issues.

Making changes to an existing API means evolving the API contract. Before we dive into the different ways to create an API version, let’s consider the API contract for a moment.

What is the API contract?

The API contract is the agreement between the API manufacturer and consumer. It details what the consumer can expect from the API in both machine and human read format. It is a way to establish trust and responsibility between the API manufacturer and the consumer, so that developers can build tools using that API with confidence.

An API contract is also a way to track changes to an API. He then raises questions about what falls within the scope of the API contract and what does not. Should an API contract define URIs? What about media types?

Let’s first consider URIs. Should URIs be covered by the API contract? According Roy winning , this violates the maxim that APIs should be targeted as much as possible. URIs are not driven by the API itself, but rather by what Fielding considers «out-of-band information.» According to Fielding, a client should be able to operate an API without additional information. By this interpretation, URIs are not part of the API contract.

Free But media types contained in the API Are . A client needs to know what types of environments are contained in an API in order to consume them correctly. A REST API You should include details about the types of media it contains, as customers need to know that information to use the API.

Changes to the API contract can often be mitigated with API version control. This gives existing users the opportunity to upgrade to the new version and to sunset functions and endpoints that you gradually eliminate.

Now let’s take a look at the most popular control methods of the API version.

3 types of API version control

The most common reason for controlling the API version is to honor contracts with existing API clients. Your applications may depend on how your API works. when they set it up. Just because you need to update your API doesn’t mean you’re ready to do the same for your apps.

API version control is a way to seamlessly switch from one version to another. It is the best way to finish an asset or an end point, as it can keep the functions outdated in previous versions. You can also leave notes in the API documentation detailing the development program, which will help you keep your consumers up to date and make any necessary revisions.

There are several ways to create different versions of your API. Here are some of the most common.

1. URI version control

The most common method of controlling the API version is to specify the API version in the URI itself. It is the most common method, because it is also the most effective.

Consider the following hypothetical end goal:


Easy right? All you need to do is configure the API endpoints, which you would do anyway. It also allows your customers to save assets if there is ever an update.

It’s a robust method, but it also violates one of the dictates of a good API design: that each URI must contain unique resources. It is also easy for URI versions to get out of control, which could lead to a large URI fingerprint.

The control of the URI version can also be very rigid and inflexible. It is not possible to update a single resource or a smaller portion of the general API. This means that the URI version is all or nothing. Creating a completely new version can be a daunting task, which can lead to slower production schedules.

Finally, controlling the URI version can cause problems with HTTP cache . An HTTP cache should store each version.

2. Query version control

A version approach to query parameters is also quite effective. Allows you to specify the API version as the query variable.



This approach is also quite simple to implement. It also makes it easier for the latest version of the API to be defaulted, unless another version is specified.

3. Custom headers

This method allows you to specify the version by creating custom headers using version numbers.


Curl -H "accepts-versions: 1:

This way, no filler is added to the URI.

When not apply an API version

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

As a general rule, it’s best to avoid creating a completely new version unless you’re making API-break changes for your existing users.

For example, consider adding additional information to usercategory:

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

This change would not break the API for your existing customers, so no new version would be required.

Now consider this alternative example where 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 could also indicate a change that could break the API for existing users, as they will need to understand the new type of media and semantics that ACCOMPANYING . Free however not creates the need for a completely new URI, which means that a completely new version may not be needed.

Finally, even major structural changes may not necessarily indicate the need to control the API version. Changing the playback status or duplicating a resource requires a significant overhaul of how a client interacts with an API. Free however not you definitely need a new version. A new resource does not necessarily change the API above in its structure.

Adding more information or variables to a URI isn’t ideal, but it also doesn’t mean that an API doesn’t adhere to Relaxing principles .

Final thoughts

As you can see, there are many things to consider when creating a new API version. As with most APIs, your focus will likely be on your unique taste and circumstances.

To summarize, we took a look at what an API version is. We also talked about the API contract and what it does and doesn’t cover. We discussed the most common methods used to control API versions. Finally, we discussed some gray areas that may or may not require the creation of a new API version.

Again, as a general rule, it’s best to avoid creating a completely new version if possible. This avoids the possibility of breaking your API for your existing customers. It is also preferable in terms of HTTP cache. It would be good to add more data or fields to existing URIs or you can even create versions of the environment itself.

Thinking about these potential issues will help you determine if the API version is the right approach. It also helps you consider your existing customers to make sure you abide by their agreements.