API Versioning

Definitions

1. Strategies for evolving an API without breaking existing clients. Common approaches: URL path (/v1/users, /v2/users), query parameter (?version=2), custom header (API-Version: 2), and content negotiation (Accept: application/vnd.api+json;version=2). Each has trade-offs in discoverability, cacheability, and maintenance burden.

   In plain English: Ways to update your API's design without breaking apps that depend on the old version.

   Example: "We use URL-based versioning (/v1/, /v2/) — it's the most visible and cacheable approach, even if purists prefer headers."

Related Terms

• Footgun
• Breaking Change
• idempotency
• ABI
• Architecture
• Semantic Versioning
• HATEOAS
• Idempotent Request