Expand and Contract
Add the new shape, move the callers, then remove the old one. The middle phase is the long one, and for external clients it is measured in quarters.
-
-
API Gateway
A gateway checks that the token is valid and the quota is not spent. Which invoices belong to whom is a question its backend should answer.
-
You Cannot Un-publish an API: Contracts, Compatibility, and Retirement
A field you stopped populating is a breaking change to whoever read it. The provider does not get to decide what counts as compatible.
-
Idempotency Key
The client that never received your response cannot tell success from failure. A key it chose beforehand is what lets it ask again safely.
-
Problem Details
A client matching on your error message has built a dependency on your copywriting. The type URI exists so it does not have to.
-
Breaking Change
Every breaking change except one produces an error somewhere. Redefining what a field means produces correct-looking numbers that disagree with last month’s.