Backward Compatibility
Which changes are safe, and how to make breakage a build failure.
3 to work through
-
beginner
Your API returns a JSON object. Which of these changes can break a client you have never met: adding a field, removing a field, changing a field's type, adding a value to an enum, reordering keys, or making an optional field always present?
3 min answer -
intermediate
What happens if an enterprise software vendor adds a required field to a widely-integrated interface, believing it is a minor change?
2 min answer -
advanced
Salesforce scheduled the retirement of Platform API versions 21.0 through 30.0 for the Summer '23 release and later postponed it to Summer '25, having retired versions 7.0 through 20.0 in Summer '22. After retirement, REST calls on a retired version return 410 Gone. What does a postponement of that size tell you about deprecation as a mechanism, and what would you build so that yours does not slip?
3 min answer
3 terms in this topic
Deprecation Brownout
An announced, time-boxed window in which a deprecated interface returns its retirement error, used to convert an abstract sunset date into a failure …
practiceSemantic Diffing of API Schemas
Comparing the published contract between builds and failing the build on a breaking change, so compatibility is mechanical rather than remembered.
patternTolerant Reader
A consumer that ignores fields it does not recognise and depends only on what it actually needs, so a producer can add to a contract without breaking it.
Neighbouring topics
API & Integration
General material on integrating systems through contracts.
REST Design
Resources, uniform methods, status codes and statelessness.
GraphQL
Client-specified queries, N+1 resolution and query-cost control.
gRPC APIs
Contract-first RPC, generated clients and protobuf compatibility rules.
Webhooks
Push callbacks, signature verification, ordering and at-least-once delivery.
API Versioning
URL, header and account-pinned versioning, and who carries the burden.
Contract Testing
Verifying what consumers actually rely on, without a shared environment.
API Documentation
OpenAPI as a machine-checked contract rather than as prose.
Rate Limiting
Algorithms, shared counters, and signalling rejection properly.
Idempotency Keys
Client-generated keys stored atomically with the operation they guard.
Pagination & Filtering
Offset versus cursor, stable ordering and unbounded result sets.
API Error Handling
Error shapes, retryability signals and machine-readable causes.
Event-Driven Integration
Publishing facts rather than commands, and versioning event schemas.
Message Formats
JSON, Protobuf, Avro — schema evolution and payload economics.
Schema Registry
Enforcing compatibility on events the way CI enforces it on code.
Integration Patterns
Routers, translators, splitters, aggregators and dead letter channels.
Legacy Integration
Reaching systems that cannot change, without importing their model.
Partner & B2B Integration
External contracts, onboarding, sandboxes and long deprecation windows.
APIs as Products
Ownership, lifecycle, deprecation policy and developer experience.