API Versioning Guide
Versioning Strategy Comparison
| Strategy | Example | Pros | Cons |
|---|---|---|---|
| URL Path | /api/v1/users | Simple, cacheable, visible | URL changes with version |
| Query Param | /api/users?v=1 | Optional, easy testing | Cache complexity |
| Custom Header | API-Version: 1 | Clean URLs | Not cacheable by default |
| Accept Header | Accept: application/vnd.api.v2+json | REST-compliant | Verbose, hard to test |
Semantic Versioning (SemVer)
MAJOR.MINOR.PATCH → 2.1.4 MAJOR: Breaking changes (2.x.x → 3.0.0) MINOR: New features, backward compatible (2.1.x → 2.2.0) PATCH: Bug fixes, backward compatible (2.1.4 → 2.1.5) Pre-release: 2.0.0-beta.1 Build meta: 2.0.0+build.123
API Deprecation Policy
// Response headers for deprecated endpoints HTTP/1.1 200 OK Deprecation: Sat, 01 Jan 2025 00:00:00 GMT Sunset: Mon, 01 Jul 2025 00:00:00 GMT Link: <https://api.example.com/v2/users>; rel="successor-version"
Breaking vs Non-Breaking Changes
| Breaking (Major Version) | Non-Breaking (Minor/Patch) |
|---|---|
| Removing a field | Adding new optional fields |
| Renaming a field | Adding new endpoints |
| Changing field type | Expanding allowed values |
| Changing authentication | Bug fixes |
| Removing endpoints | Performance improvements |