Query Parameter Versioning

title: "Query Parameter Versioning — ?api-version=1 in URLs" description: "Query parameter versioning uses a query string parameter like ?api-version=1 to specify the API version, combining simplicity with clean base URLs." date: 2026-06-28 lastmod: 2026-06-28 weight: 15 tags: [apis, versioning] }

Query parameter versioning passes the API version as a query parameter (e.g., ?api-version=1), providing simple client implementation and cache-friendly URLs.

What You'll Learn

• Query parameter versioning implementation
• Pros and cons vs other strategies
• Default version handling

Why It Matters

Query parameter versioning is the simplest for clients to implement and easy to test in browsers, but can be overlooked by proxies and caching layers.

Code Examples

# Query parameter versioning
@app.route('/api/users')
def get_users():
    version = request.args.get('api-version', '1')

    if version == '1':
        data = [{"id": u.id, "name": u.name} for u in users]
    elif version == '2':
        data = [{"id": u.id, "name": u.name, "email": u.email} for u in users]
    else:
        return jsonify({"error": f"Unsupported version: {version}"}), 400

    response = jsonify(data)
    response.headers['X-API-Version'] = version
    return response

# With validation and default
VALID_VERSIONS = {'1', '2', '3'}

@app.route('/api/products')
def get_products():
    version = request.args.get('v', '2')
    if version not in VALID_VERSIONS:
        return jsonify({"error": "Invalid version"}), 400

    version_map = {
        '1': lambda: [p.summary() for p in products],
        '2': lambda: [p.detail() for p in products],
        '3': lambda: [p.extended() for p in products],
    }
    return jsonify(version_map[version]())

// Express query parameter versioning
app.get('/api/users', (req, res) => {
  const version = req.query['api-version'] || '1';

  switch(version) {
    case '1':
      return res.json(users.map(u => ({ id: u.id, name: u.name })));
    case '2':
      return res.json(users.map(u => ({ id: u.id, name: u.name, email: u.email })));
    default:
      return res.status(400).json({ error: 'Unsupported version' });
  }
});

Common Mistakes

1. Non-Standard Parameter Names

/api/users?version=1 vs /api/users?api-version=1 vs /api/users?v=1. Standardize.

2. No Default Version

Always default to the latest stable version when parameter is missing.

3. Query Parameter in POST Body

Version parameter in GET query string is correct. Don't bury it in POST body.

4. Not Including Version in Cache Keys

Caches must include the version parameter in cache keys.

5. URL Length Limits

Very long query strings may be truncated by proxies or browsers.

Practice Questions

1. What does a query-versioned request look like?
2. What is the advantage of query parameter versioning?
3. What is the disadvantage?
4. Why include version in cache keys?
5. How do you handle the default version?

Answers:

1. /api/users?api-version=1.
2. Simple for clients, easy to test in browsers.
3. URL pollution, caching complexity, and URL length limits.
4. So different versions of the same resource are cached separately.
5. Default to the latest stable version when no parameter is given.

Challenge: Implement query parameter versioning with version-specific cache keys. Test that v1 and v2 requests return different cached responses.

FAQ