-
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 changes5 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
-
Breaking changes: 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 changes9 min read
-
How to deprecate an API without losing its developers
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
