How to implement API versioning in Express.js?

API Versioning in Express.js

As your API evolves, you need to make breaking changes without disrupting existing clients. API versioning solves this by maintaining multiple API versions simultaneously.

Versioning Strategies

1. URL Path Versioning (Most Common)

const v1Router = require('./routes/v1');
const v2Router = require('./routes/v2');

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

GET /api/v1/users → returns { name: 'John' }
GET /api/v2/users → returns { firstName: 'John', lastName: 'Doe' }

Pros: Simple, explicit, easy to test Cons: URL pollution, code duplication

2. Header Versioning

app.use('/api/users', (req, res, next) => {
  const version = req.headers['api-version'] || '1';

  switch (version) {
    case '1':
      return v1UserController.getAll(req, res, next);
    case '2':
      return v2UserController.getAll(req, res, next);
    default:
      return res.status(400).json({ error: `Unknown API version: ${version}` });
  }
});

GET /api/users
Headers: { "Api-Version": "2" }

Pros: Clean URLs Cons: Harder to discover, test in browser

3. Query Parameter Versioning

app.get('/api/users', (req, res) => {
  const version = req.query.version || '1';

  if (version === '2') {
    return res.json(getUsersV2());
  }
  return res.json(getUsersV1());
});

GET /api/users?version=2

Recommended: URL Path with Shared Logic

src/
├── routes/
│   ├── v1/
│   │   ├── index.js
│   │   ├── users.routes.js
│   │   └── products.routes.js
│   └── v2/
│       ├── index.js
│       ├── users.routes.js     ← only changed endpoints
│       └── products.routes.js  ← re-exports v1 if unchanged
├── controllers/
│   ├── v1/
│   └── v2/
└── services/              ← shared business logic

// routes/v2/products.routes.js
// No changes from v1 — re-export
module.exports = require('../v1/products.routes');

Deprecation Headers

When deprecating a version, inform clients via headers:

// Middleware for deprecated v1
function deprecationWarning(req, res, next) {
  res.set('Deprecation', 'true');
  res.set('Sunset', 'Sat, 01 Jun 2026 00:00:00 GMT');
  res.set('Link', '</api/v2>; rel="successor-version"');
  next();
}

app.use('/api/v1', deprecationWarning, v1Router);

Best Practices

Practice	Description
Start with versioning	Add `/v1` from the beginning
Maintain max 2 versions	Current + previous
Deprecate properly	Set sunset dates, notify users
Share business logic	Only version the API layer
Document changes	Changelog for each version
Semantic versioning	Major = breaking, minor = additions

Recommendation: Use URL path versioning — it's the most explicit, easiest to implement, and works well with API documentation tools like Swagger. Start with /api/v1 from day one, even if you don't plan to version initially.

Short Answer

Interview ready

Premium

A concise answer to help you respond confidently on this topic during an interview.

Finished reading?

Practice Problems