Misusing query parameters complicates API maintenance Misusing query parameters complicates API maintenance TL;DR: Use URL paths or headers for API versioning. TL;DR: Use URL paths or headers for API versioning. Problems 😔 Confusing parameters
High maintenance
Inconsistent versioning
Client errors
Misused queries
Backward incompatibility
URL clutter
Hidden complexity
Wrong semantics
Parameter collisions
Breaking changes Confusing parameters High maintenance Inconsistent versioning Client errors Misused queries Backward incompatibility URL clutter Hidden complexity Wrong semantics Parameter collisions Breaking changes Breaking changes Solutions 😃 Adopt URL paths
Avoid query parameters
Prefer headers
Version on breaking changes
Keep old versions running
Deprecate old versions carefully Adopt URL paths Avoid query parameters query parameters Prefer headers Version on breaking changes breaking changes Keep old versions running Deprecate old versions carefully Context 💬 When you change an API in a way that breaks existing clients, you create problems. breaks To avoid this, you must version your API. Versioning lets you add new features or change behavior without stopping old clients from working. You usually put the version number in the API URL path, HTTP headers, or, less commonly, in query parameters. Each method has pros and cons. URL path versioning is simple and visible. Header versioning keeps URLs clean but adds complexity. Query parameters can clutter URLs and can be confusing. Use versioning only for breaking changes. Managing multiple versions increases maintenance work but ensures reliability and user trust. Sample Code 📖 Wrong ❌ <?php

// Misusing query parameters for versioning
// https://eratostenes.com/api/primes?limit=10&version=2
// Version 2 is faster!

$version = $_GET['version'] ?? '1';

if ($version === '1') {
    echo json_encode(['data' => 'Response from API v1']);
} elseif ($version === '2') {
    echo json_encode(['data' => 'Response from API v2']);
} else {
    http_response_code(400);
    echo json_encode(['error' => 'Unsupported API version']);
}

// This handling with IF/Switches is another code smell <?php

// Misusing query parameters for versioning
// https://eratostenes.com/api/primes?limit=10&version=2
// Version 2 is faster!

$version = $_GET['version'] ?? '1';

if ($version === '1') {
    echo json_encode(['data' => 'Response from API v1']);
} elseif ($version === '2') {
    echo json_encode(['data' => 'Response from API v2']);
} else {
    http_response_code(400);
    echo json_encode(['error' => 'Unsupported API version']);
}

// This handling with IF/Switches is another code smell Right 👉 <?php 
// https://eratostenes.com/api/v2/primes?limit=10
// NOTICE                     /V2/
// Version 2 is faster!

$requestUri = $_SERVER['REQUEST_URI'];

if (preg_match('#^/v([0-9]+)/#', $requestUri, $matches)) {
    $version = $matches[1];
} else {
    $version = '1';  
}

switch ($version) {
    case '1':
        echo json_encode(['data' => 'Response from API v1']);
        break;
    case '2':
        echo json_encode(['data' => 'Response from API v2']);
        break;
    default:
        http_response_code(400);
        echo json_encode(['error' => 'Unsupported API version']);
} <?php 
// https://eratostenes.com/api/v2/primes?limit=10
// NOTICE                     /V2/
// Version 2 is faster!

$requestUri = $_SERVER['REQUEST_URI'];

if (preg_match('#^/v([0-9]+)/#', $requestUri, $matches)) {
    $version = $matches[1];
} else {
    $version = '1';  
}

switch ($version) {
    case '1':
        echo json_encode(['data' => 'Response from API v1']);
        break;
    case '2':
        echo json_encode(['data' => 'Response from API v2']);
        break;
    default:
        http_response_code(400);
        echo json_encode(['error' => 'Unsupported API version']);
} <?php
// Header-based API versioning example

// GET /api/primes?limit=12 HTTP/1.1
// Host: eratostenes.com
// Accept: application/vnd.myapi.v2+json
// NOTICE THE HEADER             V2  

$acceptHeader = $_SERVER['HTTP_ACCEPT'] ?? '';

if (preg_match('#application/vnd\.myapi\.v(\d+)\+json#', 
    $acceptHeader, $matches)) {
    $version = $matches[1];
} else {
    $version = '1';  
}

switch ($version) {
    case '1':
        echo json_encode(['data' => 'Response from API v1']);
        break;
    case '2':
        echo json_encode(['data' => 'Response from API v2']);
        break;
    default:
        http_response_code(400);
        echo json_encode(['error' => 'Unsupported API version']);
} <?php
// Header-based API versioning example

// GET /api/primes?limit=12 HTTP/1.1
// Host: eratostenes.com
// Accept: application/vnd.myapi.v2+json
// NOTICE THE HEADER             V2  

$acceptHeader = $_SERVER['HTTP_ACCEPT'] ?? '';

if (preg_match('#application/vnd\.myapi\.v(\d+)\+json#', 
    $acceptHeader, $matches)) {
    $version = $matches[1];
} else {
    $version = '1';  
}

switch ($version) {
    case '1':
        echo json_encode(['data' => 'Response from API v1']);
        break;
    case '2':
        echo json_encode(['data' => 'Response from API v2']);
        break;
    default:
        http_response_code(400);
        echo json_encode(['error' => 'Unsupported API version']);
} Detection 🔍 [x]Automatic [x]Automatic [x] You can detect the smell when your endpoints include ?version=1. ?version=1 Linters and API design reviews can flag query parameters used for versioning. You can detect this smell if you see clients breaking after API changes or if versioning is done inconsistently. Look for usage of query parameters to define versions or multiple undocumented methods. Check if old versions still respond but are not explicitly maintained or documented. Tags 🏷️ APIs APIs Level 🔋 [x]Intermediate [x]Intermediate [x] Why the Bijection Is Important 🗺️ API versions should map one-to-one with breaking changes in your domain model. one-to-one When you create versions for non-breaking changes, you break this MAPPER and create confusion about what constitutes a significant change. MAPPER This leads to version sprawl, where clients can't determine which version they actually need, making your API harder to consume and maintain. When API versions correspond clearly to usage contracts, clients know what data and behavior to expect. Breaking this one-to-one mapping by changing API behavior without versioning causes client confusion and runtime errors. Clear versioning keeps this mapping intact and reliable. mapping AI Generation 🤖 AI generators may create code with inconsistent or no API versioning, especially if asked for simple examples. AI generators often produce quick-and-dirty endpoints with query parameters. They optimize for speed, not semantics. AI Detection 🧲 AI tools can detect this smell by analyzing endpoint patterns, comparing response schemas across versions, and identifying minimal differences between API versions. They can suggest consolidating non-breaking changes into existing versions. Try Them! 🛠 Remember: AI Assistants make lots of mistakes Remember: AI Assistants make lots of mistakes Suggested Prompt: use API versions in the url Suggested Prompt: use API versions in the url Without Proper Instructions

With Specific Instructions



ChatGPT

ChatGPT



Claude

Claude



Perplexity

Perplexity



Copilot

Copilot



You

You



Gemini

Gemini



DeepSeek

DeepSeek



Meta AI

Meta AI



Grok

Grok



Qwen

Qwen Without Proper Instructions

With Specific Instructions



ChatGPT

ChatGPT



Claude

Claude



Perplexity

Perplexity



Copilot

Copilot



You

You



Gemini

Gemini



DeepSeek

DeepSeek



Meta AI

Meta AI



Grok

Grok



Qwen

Qwen Without Proper Instructions

With Specific Instructions Without Proper Instructions Without Proper Instructions With Specific Instructions With Specific Instructions ChatGPT

ChatGPT ChatGPT ChatGPT ChatGPT ChatGPT ChatGPT ChatGPT Claude

Claude Claude Claude Claude Claude Claude Claude Perplexity

Perplexity Perplexity Perplexity Perplexity Perplexity Perplexity Perplexity Copilot

Copilot Copilot Copilot Copilot Copilot Copilot Copilot You

You You You You You You You Gemini

Gemini Gemini Gemini Gemini Gemini Gemini Gemini DeepSeek

DeepSeek DeepSeek DeepSeek DeepSeek DeepSeek DeepSeek DeepSeek Meta AI

Meta AI Meta AI Meta AI Meta AI Meta AI Meta AI Meta AI Grok

Grok Grok Grok Grok Grok Grok Grok Qwen

Qwen Qwen Qwen Qwen Qwen Qwen Qwen Conclusion 🏁 You need to build APIs for MCPs and AIs today. API versioning protects your clients from breaking changes, but overuse creates maintenance nightmares and client confusion. Version your APIs judiciously - only when you make breaking changes that would cause existing integrations to fail. You need API versioning to keep your API reliable and backward-compatible when adding breaking changes. Using the URL path for versions is simple and clear. HTTP header versioning keeps URLs clean but adds complexity, while query parameter versioning should generally be avoided. Maintain clear version documentation, test versions thoroughly, and deprecate old versions gradually. This practice keeps your API users happy and your codebase maintainable. Relations 👩‍❤️‍💋‍👨 https://hackernoon.com/code-smell-303-how-to-prevent-breaking-existing-clients-when-you-make-changes https://hackernoon.com/code-smell-303-how-to-prevent-breaking-existing-clients-when-you-make-changes https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xii https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xii https://hackernoon.com/code-smell-272-api-chain?embedable=true https://hackernoon.com/code-smell-272-api-chain?embedable=true https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxviii https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxviii Disclaimer 📘 Code Smells are my opinion. opinion Credits 🙏 Photo by Marcus Urbenz on Unsplash Marcus Urbenz Unsplash If you program, you are an API designer. Good code is modular—each module has an API. If you program, you are an API designer. Good code is modular—each module has an API. Joshua Bloch Joshua Bloch https://hackernoon.com/400-thought-provoking-software-engineering-quotes?embedable=true https://hackernoon.com/400-thought-provoking-software-engineering-quotes?embedable=true This article is part of the CodeSmell Series. https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-i-xqz3evd?embedable=true https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-i-xqz3evd?embedable=true

Keep

Unsplash

Code Smell 05 - Comment Abusers

Buy My Book

Share your ideas with me!

Read My Stories

Buy Me a Coffee

Too Long; Didn't Read

Make resilience your competitive advantage

Code Smell 309 - Query Parameter API Versioning

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

Code Smell 05 - Comment Abusers

8 Free Cloudflare Features That Save Me $200/Month (With Examples)

How Eshita Gupta Transformed Fraud Analytics and Strengthened Financial Risk Management

A Guide on How to Build an AI-Powered Automated Product Enrichment Pipeline for Shopify

100 Days of AI Day 1: From Newsletter to Podcast, Leveraging AI for Audio Transformation

Code Smell 05 - Comment Abusers

8 Free Cloudflare Features That Save Me $200/Month (With Examples)

How Eshita Gupta Transformed Fraud Analytics and Strengthened Financial Risk Management

A Guide on How to Build an AI-Powered Automated Product Enrichment Pipeline for Shopify

100 Days of AI Day 1: From Newsletter to Podcast, Leveraging AI for Audio Transformation

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps