Tech News, Tech & Coding · Free Online Tools

IT Question Answer
Tools
Back to API Development
API Versioning Best Practices

API Versioning Best Practices

API DevelopmentBy Muhammad Fareed
api-developmentversioningbestpractices

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.

How a versioned API routes a request to the right versionClient: Calls the API. Version signal: Path, header or query. Gateway: Picks the right version. v1 handler: Existing behavior kept. v2 handler: New behavior addedClientCalls the APIVersion signalPath, header or queryGatewayPicks the right versionv1 handlerExisting behavior keptv2 handlerNew behavior added
Diagram: How a versioned API routes a request to the right version.

What is a breaking change?

Breaking (needs a new version)Non-breaking (safe in the same version)
Removing or renaming a field or endpointAdding a new optional field
Changing a field's type or meaningAdding a new endpoint
Making an optional parameter requiredAdding a new optional parameter
Changing error codes or authenticationFixing a bug to match documented behavior
Changing default sorting or paginationAdding 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

MethodExampleProsCons
URL path/api/v1/usersObvious, easy to test and cache, easy to routeURL changes between versions
Query parameter/users?version=1Simple to addEasy to forget; messy caching
Custom headerAPI-Version: 2026-01-15Clean URLsHarder to try in a browser
Content negotiationAccept: application/vnd.myapi.v1+jsonPurist REST approachComplex 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

  1. Announce the new version and the old version's end date (many teams allow 6 to 12 months).
  2. Publish a migration guide listing every change with before and after examples.
  3. Add response headers to warn clients, for example Deprecation and Sunset with the retirement date.
  4. Email registered developers and show warnings in the developer portal.
  5. Track usage per version, and contact heavy users of the old one.
  6. Retire the version on schedule, returning 410 Gone with 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.