How to Version API in Express: Simple Guide with Examples

To version an API in Express, you typically include the version number in the URL path like /api/v1/ or use headers or query parameters to specify the version. The most common and clear method is to prefix routes with the version, for example, app.use('/api/v1', routerV1) and app.use('/api/v2', routerV2).

Syntax

API versioning in Express is usually done by defining separate route prefixes for each version. This means you create different routers for each API version and mount them on different paths.

• app.use('/api/v1', routerV1): Routes for version 1
• app.use('/api/v2', routerV2): Routes for version 2

This keeps versions isolated and easy to maintain.

javascript

const express = require('express');
const app = express();

const routerV1 = express.Router();
routerV1.get('/users', (req, res) => {
  res.send('Users from API version 1');
});

const routerV2 = express.Router();
routerV2.get('/users', (req, res) => {
  res.send('Users from API version 2');
});

app.use('/api/v1', routerV1);
app.use('/api/v2', routerV2);

app.listen(3000, () => console.log('Server running on port 3000'));

Example

This example shows two API versions running side by side. When you visit /api/v1/users, you get the version 1 response. When you visit /api/v2/users, you get the version 2 response. This helps clients choose which API version to use.

javascript

const express = require('express');
const app = express();

const routerV1 = express.Router();
routerV1.get('/users', (req, res) => {
  res.json({ version: 'v1', users: ['Alice', 'Bob'] });
});

const routerV2 = express.Router();
routerV2.get('/users', (req, res) => {
  res.json({ version: 'v2', users: ['Alice', 'Bob', 'Charlie'] });
});

app.use('/api/v1', routerV1);
app.use('/api/v2', routerV2);

app.listen(3000, () => console.log('Server running on port 3000'));

Output

Server running on port 3000

GET /api/v1/users
Response: {"version":"v1","users":["Alice","Bob"]}

GET /api/v2/users
Response: {"version":"v2","users":["Alice","Bob","Charlie"]}

Common Pitfalls

Common mistakes when versioning APIs in Express include:

• Not isolating versions properly, causing route conflicts.
• Using query parameters or headers inconsistently, which can confuse clients.
• Failing to maintain old versions, leading to broken clients.

Always keep versions separate and clearly documented.

javascript

const express = require('express');

/* Wrong: Mixing versions in the same router */
const router = express.Router();
router.get('/api/users', (req, res) => {
  if (req.query.version === 'v1') {
    res.send('Users from v1');
  } else if (req.query.version === 'v2') {
    res.send('Users from v2');
  } else {
    res.status(400).send('Version not supported');
  }
});

/* Right: Separate routers for each version */
const routerV1 = express.Router();
routerV1.get('/users', (req, res) => res.send('Users from v1'));
const routerV2 = express.Router();
routerV2.get('/users', (req, res) => res.send('Users from v2'));

const app = express();
app.use('/api/v1', routerV1);
app.use('/api/v2', routerV2);

Quick Reference

• URL Path Versioning: Use route prefixes like /api/v1/ and /api/v2/.
• Header Versioning: Use custom headers like X-API-Version (less common).
• Query Parameter Versioning: Use query like ?version=1 (not recommended for clarity).
• Keep versions isolated: Use separate routers for each version.
• Document versions: Clearly explain differences and deprecation plans.

Key Takeaways

Version your API by prefixing routes with version numbers like /api/v1 and /api/v2.

Use separate Express routers for each API version to keep code clean and maintainable.

Avoid mixing versions in the same route handler to prevent confusion and bugs.

Document your API versions clearly and plan for deprecation of old versions.

URL path versioning is the simplest and most common method for Express APIs.