API versioning strategies in Express

Introduction

API versioning helps keep your app working well when you add new features or change things. It lets old and new users use the API without problems.

You want to add new features without breaking old apps using your API.

You need to fix bugs or improve your API but keep old versions working.

You want to support different clients that need different API versions.

You plan to change how your API works but want to avoid sudden breaks.

You want to organize your API routes clearly by version.

Syntax

Express

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

// Example: Versioning using URL path
app.get('/v1/resource', (req, res) => {
  res.send('Response from version 1');
});

app.get('/v2/resource', (req, res) => {
  res.send('Response from version 2');
});

Versioning can be done in different ways like URL path, headers, or query parameters.

URL path versioning is simple and easy to test in browsers.

Examples

This uses the URL path to separate versions, like /v1/ and /v2/.

Express

// URL path versioning
app.get('/v1/users', (req, res) => {
  res.send('Users from v1');
});

app.get('/v2/users', (req, res) => {
  res.send('Users from v2');
});

This checks a custom header to decide which version to use.

Express

// Header versioning
app.get('/users', (req, res) => {
  const version = req.headers['accept-version'];
  if (version === '2') {
    res.send('Users from v2');
  } else {
    res.send('Users from v1');
  }
});

This uses a query like ?version=2 to select the API version.

Express

// Query parameter versioning
app.get('/users', (req, res) => {
  const version = req.query.version;
  if (version === '2') {
    res.send('Users from v2');
  } else {
    res.send('Users from v1');
  }
});

Sample Program

This example shows two versions of a greeting API using URL path versioning. You can visit /v1/greet or /v2/greet to see different responses.

Express

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

// Version 1 route
app.get('/v1/greet', (req, res) => {
  res.send('Hello from API version 1');
});

// Version 2 route
app.get('/v2/greet', (req, res) => {
  res.send('Hello from API version 2 with new features');
});

app.listen(port, () => {
  console.log(`Server running on http://localhost:${port}`);
});

Important Notes

URL path versioning is easiest to implement and test but can clutter URLs.

Header versioning keeps URLs clean but needs clients to set headers correctly.

Always document your versioning method clearly for users.

Summary

API versioning helps keep old and new API users happy.

Common ways: URL path, headers, or query parameters.

Choose the method that fits your app and users best.