By Chris Phillips | Updated October 17, 2017 - Published October 16, 2017
API ManagementCloudHybrid Cloud
To manage and maintain any runtime system, you need a comprehensive versioning strategy. Without a clear strategy in place, how do you know which services and APIs are deployed and which version to use? This article highlights four strategies to help you manage API and service interfaces and implementations. It also presents the advantages and disadvantages for each strategy.
When you define a versioning strategy, you focus on your requirements for the following two key areas:
Version strategies often have a clear system for getting new versions into production, but with little to no regard for how to retire a service. Consider an example of a platform that runs for a few years. It might have 30 services, each with 20 different versions. Without a plan to retire a service, the platform can end up with a total of 600 instances for just one service.
For an API or service, keep no more than three of its most granular versions in production…“
By coupling a sensible versioning strategy with your management system, such as IBM® API Connect, you can reduce the number of services. For an API or service, keep no more than three of its most granular versions in production for each combination of its higher-level versions. For example, if the versioning scheme is vX.Y, every X version can have only three Y values in production. For the scheme vX.X.Y, every X.X version can have only three Y values in production.
The three production versions at each level relate to the following states:
The following table shows an example of a list with the maximum number of versions that are deployed with a one-dot strategy.
In this example, the maximum number of deployments is the number of dots plus one to the power of three.
When a new version is ready for release, it cannot go live until the following requirements are met:
By using a good API management tool, such as API Connect, you can quickly determine which consumers are using each version. You must notify them when the service becomes deprecated or superseded. If they do not migrate to the latest version, they must understand that they risk breaking their application.
In the following strategies, each version has its own branch in the source code repository. These branches are called code streams.
The one-dot strategy indicates the major version, followed by a dot, and then the minor version. This strategy has the following syntax:
This strategy has the following characteristics:
The two-dot strategy indicates the major version, a dot, the minor version, a dot, and then the fix number. This strategy has the following syntax:
The three-dot strategy is similar to the Version, Release, Modification, and Fixpack (VRMF) strategy that is used in IBM product versioning. This strategy indicates the release version, a dot, the major version, a dot, the minor version, a dot, and then the fix version. This strategy has the following syntax:
The interface and implementation are versioned independently. In this strategy, both the interface and the implementation follow a one-dot strategy. However, they can follow a more complex strategy, such as a two-dot or three-dot strategy.
The following table compares the four strategies to help you make the best choice for your services and APIs.
In this article, you learned about the importance of versioning and four strategies to help you manage it. Many more strategies are possible that were not addressed in this article. Keep in mind that no strategy is a single perfect fit.
Get the Code »
Apache KafkaAPI Management+
Use a Node.js proxy to inspect external APIs.
When you are creating APIs that will interact with blockchain, you need to watch out for a flaw that could…
Back to top