When developing a package(any piece of reusable code, like a class library to be loaded or a web service that’s accessible through HTTP) that has a published API it is necessary to have a clear separation between the API version and the codebase version of the package.
The API is what is exposed from the package for the users to consume, this should be documented clearly and the module should have thorough tests included that tests the entire published API to assert it conforms to the documented. This ensures that when a new version of the package has been rolled out.
When there is a need to redefine the API specification such that it is not compatible with the current specification, a new version of the API should be specified and this is how multiple versions of the API come into play, because there would be some consumers of the package that are relying on the current API specification and until they all have migrated to the new version both versions of the API must be made available.
The codebase version comes from the development team’s software configuration management (SCM) system, from the point of view of the consumer’s of the package this version has no significance, they should only care about the API version because that’s the only way the consumers interact with the package, through the API – the codebase can be completely rewritten in a different technology stack but if the API remains the same then the consumers shouldn’t notice a change.
The codebase version is of more interest to the maintainers of the package, the change management platform for example, which could be different from the development team. A useful (and quite common) convention for versioning codebase is Semantic Versioning. When adopting this versioning then the major version of the codebase will be linked to the API version. So for example if there is a need to redefine API version 1 into version 2, then the codebase will move from version 1.y.z to 2.0.0
There are 3 essentials that are important to get right when the plan is to have several packages made available for several consuming applications;
Continue reading Decoupling API Versions From Codebase Versions