Backward Compatibility: A Practitioner's Guide to Evolving APIs Without Breaking Clients
How to version REST endpoints, evolve GraphQL schemas, and ship mobile updates — without leaving existing users behind. Why It Matters Every deployed API is a contract. Every mobile binary installed on a user's phone is a snapshot of that contract. The moment you change a response shape, rename a field, or remove an endpoint, you risk breaking clients you cannot force-update. Backward compatibility is not about avoiding change. It is about managing change so that existing consumers continue to work while the system evolves underneath them. This article covers three layers: REST API versioning , GraphQL schema evolution , and mobile app compatibility (React Native & Flutter). Each section delivers concrete patterns and production-ready code. Part I — REST APIs The Versioning Decision REST APIs have four common versioning strategies. Each comes with tradeoffs: Strategy Example Pros Cons URI path /api/v1/users Simple, cacheable, widely understood Implies the resource itself changed; cache duplication Query parameter /api/users?version=1 Easy to implement, can default to latest Complicates routing and cache keys Custom header X-API-Version: 1 Keeps URIs clean Hard to test in browsers, invisible in logs Content negotiation Accept: application/vnd.app.v2+json Fine-grained, per-resource versioning Complex to test, requires custom media types Rule of thumb: Use URI versioning for public APIs. Use header-based versioning for internal services where you control all clients. Non-Breaking vs. Breaking Changes Not every change requires a new version: ✅ Non-breaking (no version bump needed): - Adding a new field to a response - Adding a new optional query parameter - Adding a new endpoint - Returning a new enum value (if clients handle unknowns) ❌ Breaking (requires a new version): - Removing or renaming a field - Changing a field's type (string → number) - Making an optional parameter required - Changing the response structure Pattern: Side-by-Side Versioning When a breaking cha