O mal uso de parámetros de consulta complica o mantemento de API 
 
 TL;DR: Use os camiños de URL ou os encabezados para a versión da API. TL;DR: Use os camiños de URL ou os encabezados para a versión da API. Problemas 
 
 
 
 
 
 
 
 
 
 
 
 Confusión de parámetros Alto mantemento Versións inconsistentes Erros do cliente Preguntas descoñecidas Incompatibilidade retroactiva URL de Clutter Complexidade oculta Unha equivocada semántica Parámetros de colisión Breve cambios Solucións 
 
 
 
 
 
 
 Páxinas URL Evitar os parámetros de consulta Prefiro cabezas Versións sobre romper cambios Manter as versións antigas en funcionamento Descartar as versións antigas con coidado O contexto Cando cambie unha API dun xeito que Os clientes existentes crean problemas. rompe Para evitar isto, ten que versionar a súa API. A versión permite engadir novas funcións ou cambiar o comportamento sen deter que os clientes antigos funcionen. Normalmente, coloca o número de versión no camiño de URL da API, os encabezados HTTP ou, menos frecuentemente, nos parámetros de consulta. Cada método ten os seus pros e os seus contras. a versión do camiño de URL é sinxela e visible. a versión de cabeceira mantén as URL limpas pero engade complexidade. Os parámetros de consulta poden confundir URLs e poden ser confusos. Use a edición só para romper os cambios. A xestión de varias versións aumenta o traballo de mantemento pero asegura a fiabilidade e a confianza do usuario. Modelo de código equivocado 🙂 <?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
 Xusto 🙂 <?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']);
}
 Detección 
 
 [x] Automacións Pode detectar o cheiro cando os seus puntos finais inclúen . Versións = 1 Linters e revisións de deseño de API poden marcar as consultas de parámetros usados para a versión. Podes detectar este cheiro se ves que os clientes rompen despois de que cambien as API ou se a versiónización se realiza de forma inconsistente. Buscar o uso de parámetros de consulta para definir versións ou varios métodos non documentados. Comprobe se as versións antigas aínda responden, pero non están explicitamente mantidas ou documentadas. Xogos ️ 
 
 APIs Nivel 
 
 [x] Intermediarios Por que é tan importante a bijeción ️ As versións de API deberían mapa Cambios no teu modelo de dominio. Unha a unha Cando crea versións para cambios non rupturistas, rompe esta e crear confusión sobre o que constitúe un cambio significativo. Mapas Isto leva a versións espalladas, onde os clientes non poden determinar que versión realmente necesitan, o que fai que a súa API sexa máis difícil de consumir e manter. Cando as versións da API corresponden claramente aos contratos de uso, os clientes saben que datos e comportamentos esperan. A ruptura deste mapeamento dun a un ao cambiar o comportamento da API sen versións provoca confusión do cliente e erros de tempo de execución. A versión clara mantén isto Intacta e fiable. Mapas A miña xeración Os xeradores de IA poden crear código con versións inconsistentes ou sen API, especialmente se se solicitan exemplos simples. Os xeradores de IA xeralmente producen puntos finais rápidos e sucios con parámetros de consulta. A súa detección As ferramentas de IA poden detectar este cheiro analizando patróns de puntos finais, comparando esquemas de resposta entre versións e identificando diferenzas mínimas entre as versións da API. Poden suxerir a consolidación de cambios non break-through nas versións existentes. Proba con eles! Lembra: os asistentes de IA cometen moitos erros 
 
 Prompt suxerido: usar versións de API na URL Prompt suxerido: usar versións de API na 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 ChatGPT ChatGPT Claude Claude Perplexidade Perplexidade piloto piloto túa túa ximielgos ximielgos profundidade profundidade O obxectivo é O obxectivo é Grúas Grúas Quenda Quenda Conclusión Ten que construír APIs para MCPs e AIs hoxe. A versión da API protexe os seus clientes de romper os cambios, pero o uso excesivo crea pesadelos de mantemento e confusión do cliente. Versión das súas APIs sabiamente - só cando realice cambios que causarían que as integracións existentes fracasen. Precisa de versións da API para manter a súa API fiable e retrocompatible ao engadir cambios de cambio. Usar o camiño URL para as versións é sinxelo e claro. A versión de cabeceira de HTTP mantén as URLs limpas pero engade complexidade, mentres que a versión de parámetros de consulta xeralmente debe evitarse. Manter a documentación da versión clara, probar as versións de forma exhaustiva e desprender as versións antigas gradualmente. Esta práctica mantén os seus usuarios de API felices e a súa base de código mantida. Relacións 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 Os cheiros son meus . Opinión Créditos Imaxe por que Marcelo Urbino Unsplash 
 
 Se programas, es un deseñador de API. O bo código é modular: cada módulo ten unha API. Se programas, es un deseñador de API. O bo código é modular: cada módulo ten unha API. Xesús Bloch https://hackernoon.com/400-thought-provoking-software-engineering-quotes?embedable=true Este artigo forma parte da serie 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

Este audio está producido na lingua orixinal da historia!

Demasiado longo; Ler

Make resilience your competitive advantage

Code Smell 309 - Query Parameter API Versións

Code Smell 309 - Query Parameter API Versións

About Author

COMENTARIOS

Etiquetas colgantes

ESTE ARTIGO FOI PRESENTADO EN

Related Stories

HackerNoon Decoded 2024: Celebrating Our Tech Companies Community!

HackerNoon Decoded 2024: Celebrating Our Media Community!

HackerNoon Decoded 2024: Celebrating Our Society Community!

Coñece R Systems: HackerNoon empresa da semana

HackerNoon Decoded 2024: Celebrating Our Tech Companies Community!

HackerNoon Decoded 2024: Celebrating Our Media Community!

HackerNoon Decoded 2024: Celebrating Our Society Community!

Coñece R Systems: HackerNoon empresa da semana

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps