API changes
Breaking changes, deprecations and versioning, told to the people they affect.
Start here: What is a breaking change? What counts and how to ship one, API deprecation: timeline, notice and RFC 9745 headers, API versioning best practices, for the callers' sake
-
How to deprecate a function in Python, JS, Java, Go, Rust
To deprecate a function, keep it working, mark it so callers get a warning that names the replacement, ship that in a minor release and remove it later.
API changes8 min read
-
REST API versioning: URL, header or query, which one fits
REST API versioning puts the version in the path, a header or the query string. What each means for callers, caches and announcements, with examples.
API changes6 min read
-
Stripe API versioning: how it works and what to copy
Stripe API versioning pins each account to a dated version and lets any request override it. How it works, what it costs, and what a small API can copy.
API changes7 min read
-
Protobuf breaking changes: what survives on the wire
Protobuf breaking changes happen on the wire, not in the URL. Some gRPC field changes are free, others break every client silently, and the two look alike.
API changes6 min read
-
GraphQL deprecation without a version number
GraphQL has no v1 or v2 in the URL. Fields get deprecated one at a time with a directive on one shared schema, which changes what a changelog owes callers.
API changes6 min read
-
How to write an API migration guide
An API migration guide turns a breaking change from an outage into a checklist. What it needs, when to publish it, and why a changelog entry is not enough.
API changes5 min read
-
Internal API changelogs: what changes for the other team
A public API changelog has an audience you can't reach directly. An internal one has an audience two floors away, and that changes what it owes them.
API changes5 min read
-
The API sunset header, and when to send one
The API Sunset header tells a client a version stops answering, unlike a deprecation notice. What RFC 8594 covers, and what a brownout buys you.
API changes5 min read
-
Webhook changelogs: the breaking change nobody requested
A webhook payload change breaks silently, because there is no caller to reject the new shape. What makes a payload change breaking, and how to version one.
API changes5 min read
-
API changelog: what to publish and who reads it
An API changelog is read by people deciding if their code still works next month. What each entry owes them, where it lives, and how callers subscribe.
API changes7 min read
-
API versioning best practices, for the callers' sake
Version only what breaks, put the version where callers can see it, and keep the old one running until a set date. Four schemes, compared by what they ask.
API changes7 min read
-
What is a breaking change? What counts and how to ship one
A breaking change is any change a correct caller could not survive. What counts, what does not, how to catch one in CI, and how to ship it safely.
API changes10 min read
-
API deprecation: timeline, notice and RFC 9745 headers
Deprecation is a promise with a date on it. The timeline, the notice template, the response headers, and the step that stops a sunset becoming an incident.
API changes6 min read