API version control


Version control is a term used by people in the computer software industry. But evolution is something that we all experience, and it applies to every object in the world.

In the computer software industry, we can see that every three to four years, each computer software comes with a different release / version to meet the current / modern requirements.
API version control

Version control is the practice of creating and managing multiple versions of software products. Consumers can decide which version to use according to their own needs, so does API management.

The creation of APIs always started with the idea of integrating applications with internal / external application developers. Like any other traditional software product, it always starts small and grows over time. Let’s look at the simple use case below to better understand it.

For example, we may want to enable internal / external application developers to access customer information and may start creating APIs to provide the required functionality.

As the first version, you can provide the API with read access only to customer information. Later, as the demand for applications increases, your application developers may request “write / update” access to customer information. As an API creator / developer, you can decide whether to:

  1. Provide withWrite / update access to customer informationA new version of the same API for
  2. Completely provide a separate API,To provide write / update access to customer information

The general design principle of API is to use the first method – from the perspective of application developers, new versions of API that provide us with the same functions, as well as additional functions when we deal with the same entity (customer). This will result in 2 versions with the same API:

·Customerinfo v1.0 – provides read-only access to customer information

·Customerinfo v2.0 – provides read / write / update access to customer information
API version control

Through API version control, the users of customerinfo API can decide which version to use according to their needs.

When we want to support multiple versions of the same API, as an API creator / designer, we need to consider the following 02 main design decisions:

·What is the format of the specified API version information

·How will consumers specify the API version of the selected API

When selecting the format used to specify version information, you can choose the following 02 common practices:

· Use release / build date-This allows the release / build date to be used to uniquely identify each version.

Example – version = – 20200808 “| version = – 20190102”
API version control

· use major.minor number-These numbers are used to specify different versions of the same API and can contain 1, 2, or 3 digits as part of the version number. Some API developers use the “V” prefix to indicate that it is the version number.

Example – version = – 1 “| version = – V1” | version = – 1.1 “| version = – v1.1” | version = – 1.1.1 “| version = – v1.1.1”
API version control

When deciding how to specify version information, users can choose from the following 03 common methods:

· HTTPheader -The custom HTTP header will be used to pass API version information

Example – x-customerinfoapi version: 2.1
API version control

· Query parameters-API version information will be passed as query parameters

Example – / customerinfo? Version = 2.1
API version control

· URL-The API version information is merged into the URL itself

Example – / V2 / customerinfo
API version control

As an API creator / developer, we can also combine some of the above methods and provide mixed methods for providing API version information. For example, we can use the URL method to specify the major version and the HTTP header method to specify the minor version of the API.

As you can see, API version control is a key function in API design / development, and as an API provider, enabling consumers to choose between different API versions is a key business difference.