API versioning allows a service to evolve its interface without breaking existing clients. The fundamental challenge: once an API is published and clients depend on it, every breaking change requires coordination across all consumers — which is often infeasible at scale. Good versioning strategy makes evolution possible by defining clear contracts between producers and consumers.
What Constitutes a Breaking Change
Breaking changes: removing a field from a response, renaming a field, changing a field’s data type, making an optional parameter required, changing HTTP status codes for existing conditions, removing an endpoint, and changing authentication requirements. Non-breaking changes: adding a new optional field to a response, adding a new optional request parameter, adding a new endpoint, adding a new error code for a new error condition. Understanding this distinction is prerequisite to designing a versioning strategy — the goal is to minimize breaking changes, not to version every change.
URL Path Versioning
The version is part of the URL: /v1/orders, /v2/orders. Pros: immediately visible in logs, browser-cacheable by version, easy to route to different backends, clients explicitly choose their version. Cons: not technically RESTful (the URL should identify a resource, not an API version), creates pressure to duplicate documentation, clients must update URLs to migrate. This is the most common approach for public APIs (Stripe, Twilio, GitHub) because operational simplicity outweighs theoretical purity.
Header Versioning
The version is specified in a request header: Accept: application/vnd.myapi.v2+json or a custom header Api-Version: 2024-01-15. Pros: keeps URLs clean, aligns with HTTP content negotiation semantics, supports date-based versioning (clients specify a date, not a version number — they get the API as it existed on that date). Cons: harder to test in a browser, requires documentation that most developers skip, caching requires Vary: Api-Version header to prevent version mismatches. Stripe uses date-based header versioning for internal APIs; URL versioning for public.
Query Parameter Versioning
Version as query parameter: /orders?api_version=2. Easy to override for testing (change the URL in a browser), works with standard HTTP caching. Cons: pollutes query parameters, easy to accidentally omit, semantic mismatch (query params typically filter resources, not specify API contracts). Avoid for primary versioning; acceptable as an escape hatch for debugging.
GraphQL and Versioning
GraphQL avoids versioning by design: clients request only the fields they need, so adding new fields is always non-breaking. Deprecate old fields with @deprecated rather than removing them immediately. Remove deprecated fields only after monitoring shows zero field usage (check field-level metrics in the GraphQL server). This enables continuous schema evolution without explicit versions. The trade-off: deprecated fields accumulate over time and must be actively pruned; the schema can become cluttered with legacy fields that clients are still using.
Managing Multiple Versions
Every active version is a maintenance burden. Minimize the number of supported versions: define a deprecation policy (e.g., a version is supported for 12 months after the next version releases), announce deprecation early with migration guides, and actively sunset old versions on schedule. Track version usage metrics: which clients are calling v1 vs. v2, is v1 usage declining after migration guides were published? Clients that never migrate may be internal tools or forgotten integrations — find the owners. Hard-deprecate by returning 410 Gone for sunset versions rather than silently breaking them.
See also: Meta Interview Guide 2026: Facebook, Instagram, WhatsApp Engineering
See also: Uber Interview Guide 2026: Dispatch Systems, Geospatial Algorithms, and Marketplace Engineering
See also: Scale AI Interview Guide 2026: Data Infrastructure, RLHF Pipelines, and ML Engineering
See also: Airbnb Interview Guide 2026: Search Systems, Trust and Safety, and Full-Stack Engineering
See also: Databricks Interview Guide 2026: Spark Internals, Delta Lake, and Lakehouse Architecture
See also: Anthropic Interview Guide 2026: Process, Questions, and AI Safety
See also: Atlassian Interview Guide
See also: Coinbase Interview Guide
See also: Shopify Interview Guide
See also: Snap Interview Guide
See also: Lyft Interview Guide 2026: Rideshare Engineering, Real-Time Dispatch, and Safety Systems
See also: Stripe Interview Guide 2026: Process, Bug Bash Round, and Payment Systems