4 ms·
There seems to be a confusion between versioning an API, which is the contract between a service and its clients; and versioning an implementation of that API.
by rswail 6y ago
There seems to be a confusion between versioning an API, which is the contract between a service and its clients; and versioning an implementation of that API.
I version the API with semver. If I add a new optional field, that's a bump in minor. If I add to a list of enumerated strings, that's a bump in minor.
But if I change my internal database schema, that's a change in my deployed service without any change in the API.
I use date-based release IDs for the service, because it marks a point in time of my development.
So release 2020-07-29 of MyService might support API versions 1.0, 1.1, 1.2 and 2.0. Clients using 1.2 are backward compatible with 1.0 and 1.1. Clients using 2.0 are not.
2020-07-29 is useful to SREs running MyService. It's irrelevant to the clients unless it changes that list of available semver'd API definitions.
- chme 6y ago> There seems to be a confusion between versioning an API, which is the contract between a service and its clients; and versioning an implementation of that API. Semver does not take into account ABI compatibility, which might also have a role if you version a interface with it.
- dragonwriter 6y ago> I version the API with semver SemVer is very particularly about versioning implementations of the API, not just the API itself. Only SemVer major and SemVer minor are about the abstract API, SemVer patch is about implementation changes that correct bugs in the implementation of the API, and the optional build part of SemVer (if it changes without any higher level change) is about implementation releases that have no impact on the behavior specified in the API. You can obviously use SemVer-ish versioning for APIs, but a major reason for SemVer is for automated tooling that relies on product version numbers and doesn't separately understand identifying APIs and their version numbers as implemented in the products.
- 0xEA 6y agoDude! Nothing frustrates me more than people mistaking server version with api version. It means I can’t update one piece of infrastructure at a time or you can never break api compact. Your server needs to support multiple api versions for rational progression of a distributed system.