api-versioninglisted

# API Versioning ## Versioning Strategies ### URL Path Versioning (recommended for breaking changes) ```text GET /api/v1/users GET /api/v2/users ``` Tradeoffs: - Explicit and visible in logs, proxies, and browser history - Easy to cache at the CDN level — the URL uniquely identifies the resource version - Easy to route at the load balancer - Results in some duplication of controller code - Changing the URL violates REST HATEOAS principles, though in practice this is acceptable Use this when: you have breaking changes and need maximum visibility and cacheability. ### Header Versioning ```text GET /api/users Accept: application/vnd.myapp+json;version=1 ``` Tradeoffs: - Cleaner URLs - Harder to test manually — browsers and curl require extra flags - Cannot be bookmarked or linked directly - CDN caching requires `Vary: Accept` header, which reduces cache hit rates Use this when: you need clean URLs and your clients are all programmatic (no browsers). ### Query Parameter Versioning (avoid) ```text GET /api/users?version=1 ``` This approach contaminates resource URLs with transport concerns. The version is not part of the resource identity. Do not use it. The only valid exception is temporary backward-compat support during a migration window. ## When to Version Version when the change is breaking. Not every change requires a version bump. **Breaking — requires new version:** - Removing a field from a response - Renaming a field - Changing a field's type (e.g.,