Versioning an API

Play this lesson

Not everyone updates

Garden Defense players do not all update their app. Priya's dashboard shows some phones running a version from six months ago.

A breaking change is a change that makes existing clients fail. If the server makes one, every player who has not updated loses the game until they do.

Semantic versioning

Semantic versioning (SemVer) gives a version three numbers, like 2.4.1:

Quick check

Shard Garden's API removes the seeds field. Under SemVer, which number goes up?

  1. MAJOR: 2.4.1 becomes 3.0.0
  2. MINOR: 2.4.1 becomes 2.5.0
  3. PATCH: 2.4.1 becomes 2.4.2
Show the answer

MAJOR: 2.4.1 becomes 3.0.0

Removing a field breaks apps that read it. Incompatible changes raise the MAJOR number, which warns everyone to check their code.

Stripe's dated versions

Stripe, the payment company, names API versions by date, like 2026-09-30.endive. Its monthly releases have no breaking changes. Twice a year, a new major release starts with breaking changes.

Each account stays on its default version until its owner upgrades, and code can ask for a version with the Stripe-Version header. Old integrations keep working.

Where the version goes

Quick check

Stripe moves every account onto breaking changes automatically.

Show the answer

False

An account stays on its default version until its owner upgrades. That is the point of versioning: nobody breaks without choosing to.

Player message

#bug-reports, @mossy
I didn't update anything and now my garden won't load!! I play on my old tablet.

Remy shipped /v2/gardens and switched off /v1 the same day. What should Remy have done?

  1. Kept /v1 working until old apps stopped using it, while asking players to update
  2. Nothing: old tablets are not supported
  3. Renamed /v2 back to /v1
Show the answer

Kept /v1 working until old apps stopped using it, while asking players to update

The old tablet's app only knows /v1. Running both versions for a while lets players update in their own time.

Deprecate, measure, remove

First mark /v1 deprecated: still working, but on its way out. Count requests per version in the logs, and show an update message in old apps. Remove /v1 only when its count is close to zero.

Bolt says: Next: three styles of API, REST, GraphQL and RPC.

Fact-checked 12 October 2026