All insights
EngineeringProduct5 min read
The API contract you don't break
Breaking an API is a one-way trust event. Once developers can't rely on you, you don't get the relationship back without years of effort.
Every API is a contract. Whether it's a paid commercial API or a side-project repo with 200 stars, breaking that contract is one of the few actions that costs trust permanently. Developers remember.
What breaking actually looks like
- Removing a field that downstream code depended on.
- Changing a response shape in a way that crashes parsers.
- Tightening a validation rule that previously let things through.
- Deprecating an endpoint without a real migration path.
How to evolve without breaking
Add new fields rather than changing existing ones. Add new endpoints rather than changing semantics. Use explicit versioning when breaking changes are unavoidable, and give years — not months — of overlap. And announce changes far in advance through the channels developers actually read.
Every breaking change is a one-way trust event. Treat them like surgery — rare, planned, and only when nothing less invasive will do.