API Versioning Best Practices

Every API changes over time. New features are added, data structures evolve, endpoints are redesigned, and performance optimizations require response format changes. Without a versioning strategy, every change risks breaking the mobile apps, websites, and integrations that depend on your API. One unannounced field rename can crash thousands of client applications instantly.

API versioning solves this by letting you introduce changes in a new version while keeping the old version running. Existing clients continue working on v1 while new clients adopt v2. This guide covers every versioning strategy, when to version, what constitutes a breaking change, how to deprecate, and practical implementation across multiple frameworks.

What Is API Versioning?

API versioning is the practice of assigning version identifiers (v1, v2, v3) to different iterations of your API. Each version represents a stable contract — clients that integrate with v1 know exactly what request format to send and what response to expect, regardless of what v2 or v3 look like.

Real-world analogy: Think of textbook editions. The 3rd edition of a textbook has updated content, but students who bought the 2nd edition can still use it — the bookstore stocks both. Eventually the 1st edition goes out of print (deprecated), but it doesn't happen overnight. API versioning follows the same principle.

Without versioning, you are forced to either: never change anything (impossible for evolving products), or change everything and break all existing clients simultaneously (unacceptable for production APIs with real users).

When Should You Create a New API Version?

Not every change requires a new version. The key question: "Will this change break existing clients?" If yes, it needs a new version. If no, it can go into the current version.

Breaking Changes (Require New Version)

Non-Breaking Changes (No New Version Needed)

API Versioning Strategies

1. URL Path Versioning (Most Popular)

The version number is part of the URL path. This is the most widely used approach — GitHub, Stripe, Google, and Twitter all use it. Its main advantage: the version is immediately visible, obvious to developers, cacheable by CDNs, and requires zero special configuration in clients.

GET /api/v1/users         → Version 1
GET /api/v2/users         → Version 2
GET /api/v3/users/123     → Version 3

// Express.js implementation
const v1Router = express.Router()
const v2Router = express.Router()

v1Router.get("/users", getUsers_v1)
v2Router.get("/users", getUsers_v2)

app.use("/api/v1", v1Router)
app.use("/api/v2", v2Router)

// Client usage (explicit, no ambiguity)
fetch("https://api.example.com/v2/users")

2. Custom Header Versioning

The version is specified in a custom HTTP header. This keeps URLs "clean" (no version in the path) but makes the version invisible in browser address bars and harder to test without tools like Postman. It's more common for internal APIs where all clients are controlled.

// Request with version header
GET /api/users
API-Version: 2
// or: X-API-Version: 2

// Express.js middleware
function versionMiddleware(req, res, next) {
  req.apiVersion = parseInt(req.headers["api-version"]) || 1
  next()
}

app.get("/api/users", versionMiddleware, (req, res) => {
  if (req.apiVersion === 2) return getUsers_v2(req, res)
  return getUsers_v1(req, res)
})

3. Accept Header Versioning (Content Negotiation)

The version is embedded in the Accept header using a custom MIME type. This is the most "RESTful" approach in theory (using content negotiation for versioning) but the least developer-friendly in practice — the syntax is complex and unfamiliar to most developers.

// Accept header versioning (GitHub uses this)
GET /users/123
Accept: application/vnd.example.v2+json

// Breaking down the MIME type:
// application/   → category
// vnd.example.  → vendor namespace
// v2            → version
// +json         → format

// GitHub's actual approach:
Accept: application/vnd.github.v3+json

4. Query Parameter Versioning

The version is passed as a query parameter. This is simple to implement but has downsides: it's optional (clients can forget it), mixes versioning with business parameters, and complicates caching. Used less frequently in practice.

// Query parameter versioning
GET /api/users?version=2
GET /api/users?api-version=2024-01-15  (date-based, used by Azure)

// Downside: easy to forget, defaults to latest (dangerous)
GET /api/users  → Which version? Depends on server default.

Versioning Strategies Compared

API Deprecation Strategy

Deprecation is the process of phasing out an old API version responsibly. You never just "turn off" a version without warning — that breaks clients and destroys trust. A proper deprecation follows a timeline:

// Deprecation response headers
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"

// After sunset date:
HTTP/1.1 410 Gone
Content-Type: application/json
{
  "error": "This API version has been removed",
  "message": "Please migrate to v2",
  "documentation": "https://docs.example.com/migration-guide",
  "successor": "https://api.example.com/v2/users"
}

Common API Versioning Mistakes

Best Practices

Versioning Decision Guide

Frequently Asked Questions

Related Articles & Tools