At work, you love shipping new features to your product. At home, you dread installing software updates. You love change, you hate change.
Most APIs deliver new features continuously. Most of these features are designed to be backwards-compatible, so you can start using them right away. Breaking changes are put behind new API versions so current integrations don’t break.
Point-in-time API versioning
Whenever you make a breaking change, you cut a new API version and call it a day. For smaller APIs, this works great. You aren’t making many breaking changes and clients can update when they want. It’s also the best tool to combat past design mistakes.
However, making breaking changes leaves your developers is an awkward place. Do they upgrade now or do they wait for the next breaking change so they only need to upgrade once. When new versions are created on an as-needed basis, your customers have no idea when to expect new versions.
I looked at the time between API versions for Stripe (where I work) It’s easy to calculate because we use dates are for our API versions. For Stripe, a new version (which means a breaking change) is introduced, on average, every 27 days. But it varies wildly. Sometimes new versions are released less than two days apart!
Ride the release train
Browsers, programming languages, and operating systems have their release schedule down to a science. Users can expect a new version on a regular cadence.
A new stable version Rust comes out every six weeks. For Chrome and Firefox, it’s five to eight weeks. Ubuntu releases two majors versions a year. Your API shouldn’t be different.
By now, you probably think I’m crazy. “Kyle”, you say, “My agile team plans sprints on a two-week basis. We can’t wait six weeks to ship features. Think of our velocity!”.
Don’t worry, your scrum is safe. You can continue to push new features at a rapid pace, as long as they’re behind feature gates. For consumers of the nightly API, your feature will have launched. You’ll then need to wait for the next release to come around for it to be public.
Adding consistency to your release process means developers can confidently upgrade without fear of repeating the process in a few days.