How to version a REST API

· Category: API & REST

Short answer

API versioning allows services to introduce breaking changes while maintaining compatibility for existing consumers.

Steps

  1. Choose a versioning strategy: URL path, query parameter, custom header, or content negotiation.
  2. Document the versioning policy and deprecation timeline clearly.
  3. Maintain backward compatibility within a major version by adding optional fields.
  4. Release new major versions only for unavoidable breaking changes.
  5. Monitor usage of old versions and communicate sunset dates.

Tips

  • URL versioning is the most discoverable and easiest to cache.
  • Header versioning keeps URLs clean but complicates testing with browsers.
  • Never version individual endpoints inconsistently within the same API.
  • Provide migration guides when deprecating old versions.

Common issues

  • Clients hardcoding versioned URLs and never upgrading.
  • Version proliferation increasing maintenance burden.
  • Breaking changes introduced in minor versions violating semantic expectations.
  • Caches serving stale responses when version is in the header.

Example

curl -X GET https://api.example.com/users   -H "Accept: application/json"   -H "Authorization: Bearer $TOKEN"

This curl command demonstrates a standard GET request with headers for content negotiation and bearer token authentication.

Additional context

Applying these principles consistently across projects leads to more maintainable systems, clearer team communication, and better outcomes for end users. Regular review and refinement of practices ensure continuous improvement.