- Treat APIs as immutable.
- Any mutation results in a wholly new API version, not a patch or minor update.
- The developer will learn what changed, and how much changed by reading the patchnotes, not looking at which semver numbers changed. This is probably a healthy practice to encourage.
- Don't change APIs so much. The interface should be very carefully designed and tested and shipped like an NES cartridge: consider it impossible to fix once its shipped.
Therefore just start with `1` and increment each time.
The reason I don't like semver is that it's a developer convenience that leads to sloppy practices. You built your product against a specific API. If the API changes, you need to re-run your entire API evaluation, testing, blessing workflow. If the delta is tiny (what would have been a patch change) then yay, your task is likely going to be very simple. But you shouldn't see a bump version update and decide you can cut corners.
I do think that with web APIs specifically, the surface area is a lot smaller — the HTTP interface is literally all you touch — so semver, in its purest form, is actually completely enforceable as long as you understand the API schema.
Our team has talked a lot about either hard-enforcing or automatically applying semver where applicable. My question to you is — does this sound reasonable, and if you knew a semver contract was actually bound to implementation (i.e. guaranteed and not implied), would you trust it more?
What's the practical value you're hoping to gain by hard-enforcing semver, especially if the surface area of HTTP APIs is a lot smaller? And this isn't a loaded question. I might just not be privy to your team's needs.
Also consider (and this again falls within the realm of personal opinion) the value of achieving _maximum possible statelessness_ as a developer. If I'm reading you right, you're asking me to know and remember, and probably write down somewhere, that your API's versioning means something different than others. So I now have another branching path to maintain: how to behave when your API changes. What I like about the simple numbered API schema is that I can come back to the API usage in a stateless manner. I just see that the number is different and I know what to do: learn what changed and decide if I have to act on it. Of course I could do this by looking at a semver as a unique identifier without semantic meaning, but that kind of leads to my initial point: encourage best practice by not giving the developer a semantic shortcut to which they can abdicate responsibility.
I’m asking questions because we provide tools that standardize the API development experience. Semver is trustable if the tools create the contract instead of the developer that decides to build the API. We deliver the tools that create the contract.
In this sense, APIs built and delivered atop our platform don’t need to “encourage best practice,” best practice is — or at least can be — hardcoded in with no potential for footguns.
Your concerns about semver are well-founded. I’m asking questions because I’m pondering aloud if we can fix them and change semver — with respect to APIs — from a social contract to a coded contract, and include tools necessary to inform end-users of API changes. :)
Does that make more sense?
With two days before my first vacation of the year, my brain is a pile of mush. I'm going to politely and apologetically bow out of this conversation. =)
Bounding to implementation is just the easiest way out -- if your policies, tests and protocols consistently fail to uphold that abstraction, then the you can fallback to this very simple (presumably innefficient) strategy to do so.
But I, as a dev, just want a stable API, and I don't care how it's done.
The gap I see a lot starts with a bad versioning strategy and continues through bad API analytics to bad communications for developers.
The API provider should be able to understand all of the individual clients to the point where they can decide to progressively migrate them one-by-one, if necessary. There shouldn't be a need to use metadata like IP addresses or user-agents to try and identify the clients. Unless someone has walked through these scenarios ahead of time, it's difficult manage when issues arise.
I feel like code bloat would be hard to maintain. Obviously I could take two endpoint handlers that have the same functionality and move their behavior into a shared function, but there's also tests to consider. As time went on, I'd have a pile of tests running against seemingly random versions.
Eg, `test_blog_create()` might test v1 and v2 of the API as that specific endpoint didn't change, but suddenly in v3 the API _does_ change, so now I need to write a slightly different test to handle that new functionality. `test_blog_create_v3()` or w/e.
I'm not arguing against it, merely noting what I've previously thought about as problematic for implementing versioned APIs.
Thoughts on how best to manage the code base?
Two approaches I've taken, with a blogpost worth of thoughts on them:
1. Every version is a whole new database/webserver stack. You shut the oldest one down when the last customer migrates off it. The bloat is real, but it's dead simple and it works.
2. A single database with a webserver that exposes all the versions. The contract is that the database shall not undergo destructive migrations. Only additive migrations. Or if you must, modify schema in a way that you can deterministically generate every previous API's view. Again, discard older versions when the last customer has been migrated off.
I'm sure you can immediately smell some problems with either of these approaches. Sacrifices are definitely made.
That means data is different between API versions?
For testing you then have your usual set of tests for the backend, but for the frontend you just test if the translation between public and internal API is correct. Very easy to test for in most cases. If you then organize your tests exactly like your frontend Version, i.e. some kind of inheritance, you only ever have to add tests for the changes in your new Version.
It is definitely more work than just having one ever changing API, but it's not that much of a hassle imho.
Note that the phrase non-overlapping is where all the complexity is hidden; it’s actually tricky to guarantee that an addition hasn’t changed any existing queries. For example, adding an enum value will mess up clients who query with max(enum_value). Technically, they’re not sending the same bytes, so the change is non-overlapping, but the client might disagree :)
Semver is important for knowing whether or not to evaluate for breakages. You can theoretically combine both of these by making the date the patch version or supplying it as a version metadata
It can be very useful for continuous improvement and handling forward compatibility. Here's how Stripe do it:https://stripe.com/en-fr/blog/api-versioning, we found that very convenient.
The trade off is that AWS has some godawful APIs (DynamoDB has the least intuitive API I have ever worked with). But they’re stable.
If you go with a date-based approach and create a process + contract whereby you guarantee API stability and / or deprecation date, the developer always knows exactly how much time they have before an upgrade.
If you publish API version 1.0.0, and then internally you fix something and publish 1.0.1 (remember: a patch doesn't change the interface at all), should you continue to serve both the 1.0.0 and 1.0.1 APIs? How are they different from the consumer's perspective? What if your reason to release 1.0.1 is to fix a security issue - in what world is it ethical to continue to serve 1.0.0? If you can discontinue serving 1.0.0 at any time (because of a security patch released with 1.0.1), then you can't offer any long-term durability guarantees for early patch versions, and so indeed, offering older patch versions (when newer patches didn't fix security issues) is more likely to break your consumers when you're forced to discontinue older patch versions for security reasons, than if you refused to serve patch-level variants in the first place.
Because you, as upstream, have no control over whether the pure addition of fields will break downstream (since downstream may or may not be strict about what they accept), you should only offer semantically versioned minor releases if you're willing to guarantee durability for earlier minor versions, and can maintain multiple minor versions of your API in parallel. If not, then be explicit about the potential of your changes to break downstream - use timestamps and document sunset dates.
We're talking about HTTP APIs, right? Then neither. These are solutions with bad trade-offs for the problem at hand.
Version the link relations. This follows the principles that make the Web successful (a.k.a. REST). If that seems weird to you¹, consider the following:
You have a personal homepage type Web site. When you change or add or remove a document, do your users need to upgrade their user agent to keep using the site? Why not?
----
¹ Numerous developers are so enamoured with putting a version number into document URIs that they cannot fathom not doing it. This is another mutilation of the mind à la Dijkstra.
https://events.pagerduty.com/generic/2010-04-15/create_event...
Customers there would sometimes ask if that API was still relevant given its date is 9+ years old.
In Shopify’s case, where there are quarterly version bumps and deprecation over time, date based makes better sense.
My high-level feeling is that it’s just way more difficult to ship a SaaS API than a Ruby Gem, so adding semver to that is just another layer of API management everybody has to agree on. Do you agree with this assessment?
The result is that API version handles need to prioritize different information. Libraries need a format that makes it easy to ballpark the size of changes between arbitrary not-strictly-sequential versions. SaaS APIs need a form that makes it easy to infer support windows and end-of-life status.
You can infer that from the Release Date though. (e.g. Version 3.4.2 Released on 2019-12-17) To me the power of Semver is that it conveys complex relations between version iterations.
For example:
- 3.4.1 -> 3.4.2 is just fixing bugs in existing functionality
- 3.4.2 -> 3.5.0 is an upgrade containing non-breaking changes
- 3.5.0 -> 4.0.0 is an upgrade containing breaking changes
As a developer, Semver + release date seems to convey everything date based versioning does plus I get the advantage of understanding at glance the importance and risk profile of each release.
Note, this system does not reduce my obligation to run my own tests to verify that the version has in fact lived up to its intention (i.e. a minor version bump did not introduce a breaking change). Even though my obligation is not reduced, it does act as a filter to help prioritize development time for evaluation of performing upgrades.
Do you think a combination of the two is possible, and how do you think that might work?
year.month.minor.patch?
But with semver you can say: ok, I want every new version up to a new minor version (all fixes). While with a date based version you don't know how 'breaking' the changes will be.
This is a good point. Good changelogs, like any documentation, take a lot of effort and so are unfortunately quite rare.
As an API consumer, to me the ideal upgrade-related documentation includes:
* Detailed release notes for each released version
* For non-GA releases like alpha/beta/RC's, describe the changes since the last small release -- typically consumers of a beta are following dev quite closely
* For GA releases, pretend the alpha/beta/etc don't exist at all. Describe the delta from the last GA release. Consumers don't care about the fix for a bug in a beta they never even knew existed.
* When you do breaking changes, provide upgrade guidance, like "If you were doing x before, now you should do y + z instead"
* If appropriate, consider also keeping separate upgrade guidance documentation for major breaking changes, for those laggard consumers that are going from a much older version like 2.x to 4.x. This allows someone to follow more of a checklist to get up-to-date without having to read 900 pages of individual release notes
You can do this with date-based version, but it's much harder as a consumer to figure out unless there's very good documentation. If I'm upgrading from "2.0.4" to "4.1.1", I know as a absolute minimum starting point I will be looking at release notes for "3.0" and "4.0" and from that, I should get a pretty good sense of the overall effort involved. If I'm upgrading from "2016-11-05" to "2019-12-19", how do I do the equivalent evaluation?
Do you feel like you’d trust a company’s API more if you could peruse the API changelog more easily?
And sometimes you also discover new features that can be really useful.
Thanks for the feedback. Can definitely see that changelogs are really underinvested in across the industry, and it’s useful to have people mention how valuable they are.
If I have a bug, it's a breaking change. If I fix this bug, it's also a breaking change.
On one extreme you had certain developers (who I am sympathetic to because it's my personality) who were loath to ever label something 1.0 because it implies Doneness and a freedom from bugs that can never be so. On the other side you had people at chop shops who would bump the major version of some boxed product every time they fixed two bugs. Even if you as a good developer did the research to discover that 0.7.6 of Package A was solid and 5 years older than Package B 7.6, there was a good chance someone above you would declare 7.6 > 0.7.6 and that it was paid-for software so "We can get support from them" and force you to work with a shittier product.
So "we" developers do what we almost always do: we cast about for a better solution and landed on one that made the meaning of version numbers opaque to anyone outside the guild of mages writing code.
In short, semantic versioning may suck hard, but it sucks less.
Semver is like unsound type systems or TDD, most of the time it's okay, until it isn't.
Google's proposed a "stability" semantic as a third option[0]. TL;DR no breaking changes in the Stable channel but you can add backwards-compatible[1] features in-place.
A permanent Beta channel that's a superset of Stable lets users choose how change-tolerant they are. This lets API producers launch features earlier, knowing they will only impact risk tolerant users if breaking changes are needed. Theoretically this reduces the need for breaking changes in Stable, which require a new Major version.
For example, 5.x.x is currently stable, so you release 6.0.0-rc1 (2, 3, ...)?
When you all think about API versioning, what makes the most sense to you — a semver approach (major.minor.patch) a la NPM, or a date-based approach (2020-01-07) a la AWS? Or is some combination of the two desirable?
At Standard Library [0] we both allow people to publish APIs but also publish API proxies on behalf of partners (Stripe, Slack + others) using a semver approach. It’s not perfect but theoretically enforceable (schema parameter additions can be forced to require a minor update, schema parameter removals can be forced to require a major update). We’ve just stuck to this semver approach based on intuition and haven’t had negative feedback about it, but I do like the idea of time-based versioning.
Would love thoughts! If you want to play around you can build your own APIs using https://code.stdlib.com/, which uses the FunctionScript specification [1] to enforce HTTP request schemas.
[0] https://stdlib.com/
[1] https://github.com/FunctionScript/FunctionScript