API Versioning

You launch an API. 500 developers integrate with it. Six months later, you need to change the response structure, rename a field, remove a deprecated property, change a data type. If you deploy the change, 500 applications break overnight.

This is the API versioning problem. Once an API is public, every response format and behavior becomes a contract. Changing that contract without warning is like a bank changing your account number without telling you, everything connected to it breaks.

API versioning lets you evolve your API while keeping old consumers working. You introduce a new version (v2) with the changes you need, while v1 continues to function exactly as before. Consumers migrate on their own schedule. Nobody breaks.

Stripe, GitHub, Twilio, Google, every serious API provider has a versioning strategy. It's not a technical luxury; it's a business necessity. Breaking your consumers' integrations is the fastest way to lose them.

1. URL path versioning (most common):

GET /api/v1/users/123
GET /api/v2/users/123

Pros: Explicit, easy to understand, easy to route. Cons: URL changes when version changes, cache keys differ per version.

2. Header versioning:

GET /api/users/123
Accept: application/vnd.myapi.v2+json

Pros: Clean URLs, version is metadata not resource identity. Cons: Less visible, harder to test in a browser, easy to forget the header.

3. Query parameter versioning:

GET /api/users/123?version=2

Pros: Simple to add. Cons: Mixes versioning with query logic, easy to omit.

4. Date-based versioning (Stripe's approach):

Stripe-Version: 2024-12-01

Stripe pins each API key to the version that existed when the key was created. Changes are rolled out by date. Your integration uses the API as it existed on the date your key was created, unless you explicitly update.