How to Use Query Parameter Versioning in REST APIs

Use query parameter versioning by adding a version key like ?version=1 to your API URL. This lets clients specify which API version to use without changing the URL path or headers.

Syntax

Query parameter versioning uses a URL parameter to specify the API version. The general syntax is:

https://api.example.com/resource?version=1

Here:

• https://api.example.com/resource is the base API endpoint.
• ?version=1 is the query parameter indicating version 1 of the API.

http

GET /resource?version=1 HTTP/1.1
Host: api.example.com

Example

This example shows a simple Node.js Express server that reads the version query parameter to return different responses based on the API version requested.

javascript

import express from 'express';
const app = express();

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

  if (version === '1') {
    res.json({ message: 'Response from API version 1' });
  } else if (version === '2') {
    res.json({ message: 'Response from API version 2 with new data' });
  } else {
    res.status(400).json({ error: 'Unsupported API version' });
  }
});

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

Output

Server running on http://localhost:3000

// Example requests:
// GET http://localhost:3000/resource?version=1
// Response: {"message":"Response from API version 1"}

// GET http://localhost:3000/resource?version=2
// Response: {"message":"Response from API version 2 with new data"}

// GET http://localhost:3000/resource?version=3
// Response: {"error":"Unsupported API version"}

Common Pitfalls

• Missing default version: Not providing a default version can cause errors if the client omits the version parameter.
• Ignoring unsupported versions: Always handle unsupported versions gracefully with clear error messages.
• Mixing versioning methods: Avoid combining query parameter versioning with other versioning styles like URL path or headers to reduce confusion.

javascript

/* Wrong: No default version and no error handling */
app.get('/resource', (req, res) => {
  const version = req.query.version;
  if (version === '1') {
    res.json({ message: 'v1' });
  } else if (version === '2') {
    res.json({ message: 'v2' });
  }
  // No else block - client gets no response if version missing or invalid
});

/* Right: Default version and error handling */
app.get('/resource', (req, res) => {
  const version = req.query.version || '1';
  if (version === '1') {
    res.json({ message: 'v1' });
  } else if (version === '2') {
    res.json({ message: 'v2' });
  } else {
    res.status(400).json({ error: 'Unsupported API version' });
  }
});

Quick Reference

Tips for using query parameter versioning effectively:

• Use a clear and consistent query parameter name like version.
• Provide a default version if the parameter is missing.
• Return clear error messages for unsupported versions.
• Document supported versions for your API users.
• Keep versioning logic centralized in your API code for easy updates.

Key Takeaways

Add a query parameter like ?version=1 to specify API versions in URLs.

Always provide a default version and handle unsupported versions with errors.

Keep versioning consistent and avoid mixing with other versioning methods.

Document your API versions clearly for client developers.

Centralize version handling in your API code for easier maintenance.