API versioning strategies in Node.js - Step-by-Step Execution

Concept Flow - API versioning strategies

Client sends API request

↓

Check version info in request

↓

Route to matching version handler

↓

Route to matching version handler

↓

Route to matching version handler

↓

Use default API version handler

↓

Send response back to client

The server checks the client's request for version info in URL, headers, or query parameters, then routes to the correct API version handler or defaults.

Execution Sample

Node.js

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

app.get('/api/v1/data', (req, res) => res.send('Data v1'));
app.get('/api/v2/data', (req, res) => res.send('Data v2'));

app.get('/api/data', (req, res) => {
  const ver = req.get('version') || req.query.version;
  if (ver === '1') {
    res.send('Data v1');
  } else if (ver === '2') {
    res.send('Data v2');
  } else {
    res.send('Default data');
  }
});

app.listen(3000);

This code routes requests to different handlers based on the version in the URL path, headers, or query parameters.

Execution Table

Step	Request URL	Version Detected	Handler Chosen	Response Sent
1	/api/v1/data	v1 (from URL path)	v1 handler	'Data v1'
2	/api/v2/data	v2 (from URL path)	v2 handler	'Data v2'
3	/api/data (header: version=1)	v1 (from header)	v1 handler	'Data v1'
4	/api/data (query: ?version=2)	v2 (from query param)	v2 handler	'Data v2'
5	/api/data (no version info)	none	default handler	'Default data'
6	End of requests	-	-	-

💡 Requests stop after all examples are handled.

Variable Tracker

Variable	Start	After 1	After 2	After 3	After 4	After 5	Final
version	undefined	v1	v2	v1	v2	undefined	undefined
handler	undefined	v1 handler	v2 handler	v1 handler	v2 handler	default handler	default handler

Key Moments - 2 Insights

How does the server know which API version to use if the version is not in the URL?

The server checks other places like headers or query parameters for version info, as shown in execution_table rows 3 and 4.

What happens if the client does not specify any version?

The server uses a default handler to respond, as shown in execution_table row 5.

Visual Quiz - 3 Questions

Look at the execution table, what version is detected at step 3?

A No version detected

B v2 from URL

C v1 from header

D v2 from query param

💡 Hint

Check the 'Version Detected' column at step 3 in the execution_table.

At which step does the default handler respond?

A Step 2

B Step 5

C Step 4

D Step 1

💡 Hint

Look for 'default handler' in the 'Handler Chosen' column.

If the version was only checked in the URL path, which steps would fail to route correctly?

A Steps 3 and 4

B Steps 1 and 2

C Step 5 only

D All steps would route correctly

💡 Hint

Check which steps detect version from header or query param in the execution_table.

Concept Snapshot

API versioning routes client requests to correct code versions.
Common ways to specify version:
- URL path (e.g., /api/v1/)
- HTTP headers (e.g., 'Accept-Version')
- Query parameters (e.g., ?version=2)
If no version found, use default.
This helps keep old and new API versions working together.

Full Transcript

API versioning strategies help servers handle different versions of an API. The server looks for version info in the request URL path, headers, or query parameters. If it finds a version, it routes the request to the matching version handler. If no version is specified, it uses a default handler. For example, requests to /api/v1/data go to the version 1 handler, while /api/v2/data go to version 2. If the version is in a header or query parameter, the server still routes correctly. This approach allows clients to use different API versions without breaking existing functionality.

Practice

1. Which of the following is the simplest and most common method to version a Node.js API?

easy

A. Using content negotiation with the Accept header

B. Using a custom HTTP header to specify the version

C. Adding a version query parameter, like ?version=1

D. Including the version number in the URL path, like /v1/users

Solution

1. Step 1: Understand common API versioning methods

   API versioning can be done via URL path, headers, query params, or content negotiation.

2. Step 2: Identify the simplest and most common method

   Including the version in the URL path is easiest to implement and understand.

3. Final Answer:

   Including the version number in the URL path, like /v1/users -> Option D

4. Quick Check:

   URL path versioning = simplest method [OK]

Hint: URL path versioning is easiest to spot and use [OK]

Common Mistakes:

• Thinking headers are simpler for beginners
• Confusing query params with URL path
• Assuming content negotiation is the default

2. Which syntax correctly defines a route in Express.js for version 2 of an API using URL path versioning?

easy

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

B. app.get('/api/users?v=2', (req, res) => { res.send('v2 users'); });

C. app.get('/api/users', (req, res) => { if(req.headers['version'] === '2') res.send('v2 users'); });

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

Solution

1. Step 1: Recognize URL path versioning syntax in Express.js

   Version 2 in URL path means the route includes /v2/ in the path.

2. Step 2: Match the correct route definition

   app.get('/api/v2/users', (req, res) => { res.send('v2 users'); }); uses /api/v2/users which matches version 2 in the URL path.

3. Final Answer:

   app.get('/api/v2/users', (req, res) => { res.send('v2 users'); }); -> Option A

4. Quick Check:

   URL path versioning route = app.get('/api/v2/users', (req, res) => { res.send('v2 users'); }); [OK]

Hint: Version in URL path means it appears in the route string [OK]

Common Mistakes:

• Using query params instead of URL path
• Checking headers inside route without version in path
• Ignoring version in route path

3. Given this Express.js code snippet, what will be the response when a client requests /api/users with header Accept-Version: 2?

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

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

medium

A. "Users v1"

B. 404 Not Found

C. "Users v2"

D. Error: Missing version

Solution

1. Step 1: Check the header condition in the route handler

   The code checks if req.headers['accept-version'] equals '2'.

2. Step 2: Determine response based on header value

   If header is '2', it sends 'Users v2'; otherwise, 'Users v1'. The request has header 'Accept-Version: 2'.

3. Final Answer:

   "Users v2" -> Option C

4. Quick Check:

   Header 'Accept-Version: 2' triggers v2 response [OK]

Hint: Match header value exactly to get correct version response [OK]

Common Mistakes:

• Ignoring case sensitivity of header keys
• Assuming URL path versioning instead of header
• Expecting 404 when route exists

4. Identify the bug in this Express.js versioning code using query parameters:

app.get('/api/users', (req, res) => {
  if (req.query.version = '1') {
    res.send('Users v1');
  } else {
    res.send('Users v2');
  }
});

medium

A. Missing route for version 2 explicitly

B. Using assignment (=) instead of comparison (== or ===) in the if condition

C. Incorrect query parameter name; should be 'ver' not 'version'

D. res.send should be res.json for API responses

Solution

1. Step 1: Examine the if condition syntax

   The condition uses = which assigns '1' to req.query.version instead of comparing.

2. Step 2: Understand the effect of assignment in condition

   Assignment returns '1' (truthy), so the if block always runs, ignoring else.

3. Final Answer:

   Using assignment (=) instead of comparison (== or ===) in the if condition -> Option B

4. Quick Check:

   Use '==' or '===' for comparison, not '=' [OK]

Hint: Use triple equals (===) for comparisons, not single equals (=) [OK]

Common Mistakes:

• Confusing assignment with equality check
• Assuming missing else block causes bug
• Thinking res.send vs res.json causes error here

5. You want to support two API versions in your Node.js app: v1 uses URL path versioning, and v2 uses a custom header X-API-Version. How should you design your Express routes to handle both cleanly?

hard

A. Define separate routes: /api/v1/... for v1, and /api/... with header check for v2

B. Use only URL path versioning for both versions to avoid confusion

C. Use query parameters for v1 and headers for v2 in the same route

D. Combine both version indicators in the URL path like /api/v1/v2/...

Solution

1. Step 1: Separate versioning methods logically

   Use URL path for v1 routes explicitly, e.g., /api/v1/....

2. Step 2: Use header check for v2 on routes without version in path

   Define routes like /api/... and check X-API-Version header to serve v2.

3. Final Answer:

   Define separate routes: /api/v1/... for v1, and /api/... with header check for v2 -> Option A

4. Quick Check:

   Separate routes for path and header versioning [OK]

Hint: Separate routes for path versioning; use header check for others [OK]

Common Mistakes:

• Mixing both versions in one URL path
• Using query params inconsistently
• Ignoring header version check in routes