Designing an API – Stable

24 Nov 2016

If you haven’t yet seen part 1, and part 2 this post vaguely follows on from those.

The final aspect of good API design that I wanted to talk about is stable. When talking about a stable API, I'm not referring to the uptime, although that is important, rather I'm referring to the ability to implement a API client against a set version of the API, without future changes causing it to break.

The pinicle of a stable API has to be the Stripe API, first released over three years ago, implementations using the first public version of the API still work today. It's hard to understate just how impressive a feat this is, particularly given the number of new features Stripe have implemented in the meantime.

So what makes a stable API so great?

Of course, continuing to support the same API whilst introducing new features isn't witout it's pitfalls. However every time I've used an API, which has later introduced a breaking change into an actively deployed version I've lost a little bit of faith in the engineering ability of that company.

So how do we develop APIs that are stable, whilst also introducing new features, I'd propose there's a couple of solutions:

Miantaining a stable API isn't without work, but assuming all users read your notification emails, bulletin board, or obscure forum, and know when you're about to release a breaking change, is unrealistic. Even with internal APIs, which are far easier to deprecate old version of, ensuring everyone is using the latest version can be almost impossible.

Stable APIs, are trustworthy APIs. Breaking changes are inevitable, but by introducing them carefully, on new endpoints, or API versions, we can create APIs that are a joy to work with, rather than a chore.