API Versioning

APIs are long-lived. As your business logic evolves, you will eventually need to make Breaking Changes. Versioning allows you to do this without breaking existing client integrations.

1. URI Versioning (Most Popular)

The version is included directly in the URL path. It's easy for developers to see and simple to route.

https://api.example.com/v1/users
https://api.example.com/v2/users

2. Header Versioning (Media Type)

The client requests a specific version via the Accept header. This keeps the URI "clean" and resource-oriented.

Accept: application/vnd.example.v2+json

3. When to Version?

• Breaking: Changing a field name, removing an endpoint, changing the data structure. (New Version Required)
• Non-Breaking: Adding a new field, adding a new endpoint. (No Version Change Needed)

4. Sunsetting Strategy

Never just turn off an old version. Use the Sunset HTTP header to communicate the date when an endpoint will be removed, and provide clear migration guides.