API Versioning Best Practices
Short answer: API versioning lets you change your API without breaking existing clients. The simplest and most common approach is putting the major version in the URL, such as /v1/users. Whatever method you pick, avoid breaking changes where you can, and announce retirements early.
Why version?
Once other people depend on your API, you cannot freely rename a field or remove an endpoint. A new version gives you room to improve while old clients keep working until they are ready to move.
What is a breaking change?
| Breaking (needs a new version) | Non-breaking (safe in the same version) |
|---|---|
| Removing or renaming a field or endpoint | Adding a new optional field |
| Changing a field's type or meaning | Adding a new endpoint |
| Making an optional parameter required | Adding a new optional parameter |
| Changing error codes or authentication | Fixing a bug to match documented behavior |
| Changing default sorting or pagination | Adding new enum values (if clients are told to expect them) |
Tell clients to ignore fields they do not recognize so additive changes stay safe.
Versioning strategies
| Method | Example | Pros | Cons |
|---|---|---|---|
| URL path | /api/v1/users | Obvious, easy to test and cache, easy to route | URL changes between versions |
| Query parameter | /users?version=1 | Simple to add | Easy to forget; messy caching |
| Custom header | API-Version: 2026-01-15 | Clean URLs | Harder to try in a browser |
| Content negotiation | Accept: application/vnd.myapi.v1+json | Purist REST approach | Complex for clients |
For most teams, URL versioning is the best default because it is visible and unambiguous. Some well-known APIs use date-based header versions instead, which suits frequent small changes.
Version at the right level
- Use major versions only in the URL (
v1,v2). Minor and patch changes should be backwards compatible and not need a new URL. - Do not create a new version for every release; each active version costs maintenance.
- Version the whole API, not individual endpoints, so clients have one clear target.
How to run two versions
app.use('/v1', require('./routes/v1'));
app.use('/v2', require('./routes/v2'));
Keep shared business logic in one place and make each version a thin layer that adapts requests and responses. This avoids copying code. Learn the Express routing basics in how to build a REST API with Express.
Deprecate with a clear timeline
- Announce the new version and the old version's end date (many teams allow 6 to 12 months).
- Publish a migration guide listing every change with before and after examples.
- Add response headers to warn clients, for example
DeprecationandSunsetwith the retirement date. - Email registered developers and show warnings in the developer portal.
- Track usage per version, and contact heavy users of the old one.
- Retire the version on schedule, returning
410 Gonewith a helpful message.
Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: <https://api.example.com/docs/migrate-v2>; rel="deprecation"
Best practices checklist
- Include a version from the first release; adding it later is painful.
- Prefer additive, backwards-compatible changes.
- Document each version and its changelog.
- Test old versions in your automated test suite until they are retired.
- Version request and response schemas together.
- Keep the number of supported versions small, ideally two.
Common mistakes
- Shipping breaking changes in the same version "just this once".
- Never retiring old versions, so maintenance keeps growing.
- Giving no notice before shutting a version down.
- Versioning in the database or code but not in the contract clients see.
Next steps
Start with good foundations in how to design a RESTful API and secure it with authentication methods. For the concept itself, read what an API is.
