Zneužití parametrů dotazu komplikuje údržbu API 
 
 TL;DR: Používejte URL cesty nebo hlavičky pro verzi API. TL;DR: Používejte URL cesty nebo hlavičky pro verzi API. Problémy 
 
 
 
 
 
 
 
 
 
 
 
 Zmatené parametry Vysoká údržba Nedůsledná verze Klientské chyby Zneužité požadavky zpětná neslučitelnost URL klávesnice Skrytá složitost Špatná semantika Parametry kolize Rozbít změny Řešení 
 
 
 
 
 
 
 Využijte URL cesty Vyhněte se parametrům Přednost hlavám Verze o přerušení změn Stará verze běží Starší verze opatrně Kontextová Když změníte API způsobem, který Existující zákazníci vytvářejí problémy. Přerušeno Abyste tomu zabránili, musíte svůj API zprovoznit. Verziování umožňuje přidávat nové funkce nebo měnit chování, aniž byste zastavili staré klienty. Číslo verze obvykle umístíte do cesty URL API, hlaviček HTTP nebo méně často do parametrů dotazu. Každá metoda má své výhody a nevýhody. URL cesta verze je jednoduchá a viditelná. Header verze udržuje URL čisté, ale přidává složitost. Parametry dotazu mohou zmatovat adresy URL a mohou být matoucí. Používejte verzi pouze pro přerušení změn. Správa více verzí zvyšuje údržbu, ale zajišťuje spolehlivost a důvěru uživatelů. Vzorový kód Špatně 🙂 <?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
 Správně 🙂 <?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']);
}
 Detekce 
 
 [x] Automatické Můžete detekovat zápach, když vaše koncové body zahrnují . Verze = 1 Lintery a hodnocení návrhu API mohou označovat parametry, které se používají pro tvorbu verzí. Tento zápach můžete detekovat, pokud vidíte, že klienti přerušují po změně rozhraní API nebo pokud se verze provádějí nekonzistentně. Hledejte použití parametrů dotazu k definici verzí nebo více nedokumentovaných metod. Zkontrolujte, zda staré verze stále reagují, ale nejsou výslovně udržovány nebo zdokumentovány. Týden ️ 
 
 API Úroveň 
 
 [x] Zprostředkování Proč je důležitý ️ API verze by měly mapovat Změny ve vašem doménovém modelu. Jeden na jednoho Když vytvoříte verze pro nepřerušované změny, přerušíte a vytvářet zmatek o tom, co představuje významnou změnu. Mapy To vede k rozšíření verzí, kde zákazníci nemohou určit, kterou verzi skutečně potřebují, což ztěžuje spotřebu a údržbu vašeho API. Když verze API jasně odpovídají smlouvám o používání, klienti vědí, jaká data a chování mohou očekávat. Porušení této individuální mapování změnou chování rozhraní API bez provedení verzí způsobuje zmatek klientů a chyby v čase spuštění. Jasná verze zachovává toto neporušené a spolehlivé. mapování Až do generace Generátory umělé inteligence mohou vytvářet kód s nekonzistentním nebo bez verzi API, zejména pokud jsou požadovány jednoduché příklady. Generátory AI často vytvářejí rychlé a špinavé koncové body s parametry dotazu. Jak na detekci Nástroje umělé inteligence mohou tento zápach detekovat analýzou vzorců koncových bodů, porovnáním schémat odezvy mezi verzemi a identifikací minimálních rozdílů mezi verzemi API. Mohou navrhnout konsolidaci nepřerušujících změn do stávajících verzí. Vyzkoušejte je! Pamatujte: Asistenti AI dělají spoustu chyb 
 
 Nabídka: Používejte verze API v url Nabídka: Používejte verze API v 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 Chatky Chatky Claude Claude Zmatenost Zmatenost Copilot Copilot Vy Vy Dvojčata Dvojčata hluboký hluboký Cílem AI Cílem AI Grochová Grochová Květen Květen Závěr Dnes potřebujete vytvořit API pro MCP a AIs. Rozhraní API chrání vaše klienty před změnami, ale nadměrné používání vytváří noční můry údržby a zmatek klientů. Vaše rozhraní API provedete rozumně – pouze tehdy, když provedete zásadní změny, které by způsobily selhání stávajících integrací. Potřebujete verzi API, aby vaše API byla spolehlivá a zpětně kompatibilní při přidávání změn. Použití URL cesty pro verze je jednoduché a jasné. Verzifikace hlavičky HTTP udržuje adresy URL čisté, ale přidává složitost, zatímco normalizace parametrů dotazu by se měla obecně vyhnout. Udržujte jasnou dokumentaci verzí, důkladně testujte verze a postupně odstraňujte staré verze. Tato praxe udržuje vaše uživatele API šťastné a vaši kódovou základnu udržitelnou. Vztahy 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/code-smell-272-api-chain?embedable=true https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxviii Disclaimer Vůně jsou moje . Názor Půjčky Fotografie od je Marcus Urbenzová Unsplashová 
 
 Pokud programujete, jste projektantem API. Dobrý kód je modulární – každý modul má API. Pokud programujete, jste projektantem API. Dobrý kód je modulární – každý modul má API. Joshua Blochová https://hackernoon.com/400-thought-provoking-software-engineering-quotes?embedable=true Tento článek je součástí série CodeSmell. https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-i-xqz3evd?embedable=true

Winner of Noonies 2020 for the award Hacker Noon Contributor of the Year - REFACTORING.

2020 - Hacker Noon Contributor of the Year in REFACTORING

2022 - HackerNoon Contributor of the Year - Clean Code

2022 - HackerNoon Contributor of the Year - Debugging

2022 - HackerNoon Contributor of the Year - Github

2022 - HackerNoon Contributor of the Year - Machine Learning

2022 - HackerNoon Contributor of the Year - Quality Assurance

2022 - HackerNoon Contributor of the Year - Refactoring

2022 - HackerNoon Contributor of the Year - Software Architecture

2022 - the Greatest Storyteller

Buy My Book

Share your ideas with me!

Read My Stories

Buy Me a Coffee

Software Engineer and Book Author

Tento zvuk je produkován v původním jazyce příběhu!

Příliš dlouho; Číst

Code Smell 309 - Query Parameter API Verzifikace

Code Smell 309 - Query Parameter API Verzifikace

About Author

KOMENTÁŘE

ZAVĚŠIT ZNAČKY

TENTO ČLÁNEK BYL PŘEDSTAVEN V

Related Stories

Coinshift Launches csUSDL, Announces Strategic Partnerships

Coinshift Launches csUSDL, Announces Strategic Partnerships

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps