API Versioning

Strategies

• URL versioning — /api/v1/users, /api/v2/users. Most explicit, easy to cache. The most popular approach
• Header versioning — Accept: application/vnd.api+json; version=2. Cleaner URL, but more complex client
• Query parameter — /api/users?version=2. Simple, but clutters the URL

Breaking change rules

• Removing a field — breaking change → new major version
• Adding a field — usually non-breaking (if clients ignore unknown fields)
• Changing a field type — breaking change

Deprecation

Maintain the old version for at least 6–12 months after announcing deprecation. Notify clients via the Sunset header and documentation.