Versioning the API
Interfaces are rarely created fully formed from scratch. They are constantly being tweaked, with new features added, and bugs or inconsistencies fixed. To better communicate these changes, it's useful to create some sort of versioning to transmit this information.
Why versioning?
The main advantage of versioning is to shape the conversation about what things are included when. This can be bug fixes, new features, or even newly introduced bugs.
If we know that the current interface released is version v1.2.3
, and we are about to release version v1.2.4
, which fixes bug X, we can talk about it more easily, as well as creating release notes informing users of that fact.
Internal versus external versioning
There are two kinds of versions that can get a bit confused. One is the internal version, which is something that makes sense for the developers of a project. This is normally related to the version of the software, usually with some help...