Examples of Versioning a Node.js API

Introduction to Versioning a Node.js API

Versioning is a crucial aspect of API development that allows developers to introduce new features, fix bugs, or make changes without disrupting existing users. By implementing versioning in your Node.js API, you can ensure backward compatibility and a smoother transition for clients relying on your service. In this article, we will explore three practical examples of versioning a Node.js API.

Example 1: Path Versioning

Context

Path versioning is the most common method of API versioning. It involves including the version number in the URL path, making it clear which version of the API clients are interacting with. This method is straightforward and easy to implement.

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

// Version 1 of the API
app.get('/api/v1/users', (req, res) => {
    res.json([{ id: 1, name: 'John Doe' }, { id: 2, name: 'Jane Smith' }]);
});

// Version 2 of the API
app.get('/api/v2/users', (req, res) => {
    res.json([{ id: 1, name: 'John Doe', age: 30 }, { id: 2, name: 'Jane Smith', age: 25 }]);
});

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

Notes

• This example demonstrates two versions of a user endpoint. Version 1 returns only the user’s name, while Version 2 includes an age attribute.
• Clients can easily choose which version to use by updating their request URL.

Example 2: Query Parameter Versioning

Context

In some cases, you may want to keep your URLs clean and use query parameters to specify the API version. This method can be helpful if you want to avoid cluttering your URL structure.

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

app.get('/api/users', (req, res) => {
    const version = req.query.version;
    if (version === '1') {
        res.json([{ id: 1, name: 'John Doe' }, { id: 2, name: 'Jane Smith' }]);
    } else if (version === '2') {
        res.json([{ id: 1, name: 'John Doe', age: 30 }, { id: 2, name: 'Jane Smith', age: 25 }]);
    } else {
        res.status(400).send('Version not supported');
    }
});

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

Notes

• In this example, clients specify the version as a query parameter (e.g., /api/users?version=1).
• This method allows for more flexibility but can complicate the logic for parsing requests.

Example 3: Header Versioning

Context

Header versioning involves specifying the version of the API in the request headers. This approach keeps URLs clean and separates versioning from the endpoint structure.

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

app.use(express.json());

app.get('/api/users', (req, res) => {
    const version = req.headers['api-version'];
    if (version === '1') {
        res.json([{ id: 1, name: 'John Doe' }, { id: 2, name: 'Jane Smith' }]);
    } else if (version === '2') {
        res.json([{ id: 1, name: 'John Doe', age: 30 }, { id: 2, name: 'Jane Smith', age: 25 }]);
    } else {
        res.status(400).send('Version not supported');
    }
});

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

Notes

• In this example, clients specify the version in the request header (e.g., api-version: 2).
• This method allows for a clean URL and can be beneficial for API consumers who prefer not to modify their URLs.

By understanding and implementing these examples of versioning a Node.js API, developers can ensure a more robust and user-friendly API experience.