El mal uso de los parámetros de la consulta complica el mantenimiento de las API 
 
 TL;DR: Utilice pistas de URL o encabezados para la versión de la API. TL;DR: Utilice pistas de URL o encabezados para la versión de la API. Problemas 
 
 
 
 
 
 
 
 
 
 
 
 Parámetros confusos Alto mantenimiento Versiones inconsistentes Errores del cliente Peticiones abusivas Incompatibilidad retroactiva URL de Clutter Complejidad oculta La equivocada semántica Parámetros de colisión Cambio de Breakout Soluciones 
 
 
 
 
 
 
 Pautas de URL Evita los parámetros de búsqueda Prefiere cabezas Versión para romper los cambios Mantener las versiones antiguas en funcionamiento Descartar las versiones antiguas con cuidado Contexto Cuando cambie una API de una manera que Los clientes existentes crean problemas. rompe Para evitar esto, usted tiene que versionar su API. El procesamiento de versiones le permite añadir nuevas características o cambiar el comportamiento sin detener el funcionamiento de los clientes antiguos. Por lo general, se coloca el número de versión en el camino de URL de la API, en los encabezados de HTTP o, menos comúnmente, en los parámetros de la consulta. Cada método tiene pros y contras. la versión de la ruta de URL es simple y visible. la versión del encabezado mantiene las URL limpias pero agrega complejidad. Los parámetros de la consulta pueden causar confusión en las URL y pueden ser confusos.Utilizar el procesamiento de versiones sólo para hacer cambios.Gestionar varias versiones aumenta el trabajo de mantenimiento, pero garantiza la fiabilidad y la confianza del usuario. Código de muestreo 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
 Derecho <?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] Es automático Puede detectar el olor cuando sus puntos finales incluyen . Versión = 1 Linters y revisiones de diseño de API pueden marcar las consultas de parámetros utilizados para la versión. Puede detectar este olor si ve que los clientes se rompen después de cambiar la API o si la versión se hace de forma inconsistente. Busque el uso de parámetros de consulta para definir versiones o varios métodos no documentados. Compruebe si las versiones antiguas todavía responden, pero no se mantienen ni documentan explícitamente. Tags ️ 
 
 APIS Nivel 
 
 [x] El Intermedio ¿Por qué es importante la bijeción ️ Las versiones de API deben mapear Cambios en tu modelo de dominio. Uno a uno Cuando crea versiones para cambios no interrumpidos, rompe este y crear confusión sobre lo que constituye un cambio significativo. Mapa Esto lleva a la dilatación de la versión, donde los clientes no pueden determinar qué versión realmente necesitan, lo que hace que su API sea más difícil de consumir y mantener. Cuando las versiones de las API corresponden claramente a los contratos de uso, los clientes saben qué datos y comportamiento esperar. La ruptura de este mapeo uno a uno al cambiar el comportamiento de la API sin versiones provoca confusión del cliente y errores de tiempo de ejecución. La versión clara mantiene esto Intacto y fiable. Mapas La generación Los generadores de IA pueden crear código con API inconsistente o sin versión, especialmente si se le piden ejemplos simples. Los generadores de IA a menudo producen terminales rápidos y sucios con parámetros de consulta. Detección Las herramientas de IA pueden detectar este olor mediante el análisis de patrones de puntos finales, la comparación de esquemas de respuesta entre versiones y la identificación de diferencias mínimas entre versiones de API. Pueden sugerir la consolidación de cambios no destructivos en versiones existentes. ¡Pruébelo! Recuerda: los asistentes de IA cometen muchos errores 
 
 Prompt sugerido: usar versiones de API en la URL Prompt sugerido: usar versiones de API en la 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 Perplejidad Perplejidad piloto piloto tú tú Gemini Gemini profundidad profundidad El objetivo es El objetivo es Grúas Grúas Quien Quien Conclusión Necesita construir APIs para MCPs y AIs hoy. La versión de la API protege a sus clientes de romper los cambios, pero el uso excesivo crea pesadillas de mantenimiento y confusión del cliente. Versión de sus APIs sabiamente - sólo cuando realice cambios revolucionarios que causarían el fracaso de las integraciones existentes. Necesita la versión de la API para mantener su API fiable y compatible con el retroceso al agregar cambios de brecha. El uso del camino URL para las versiones es simple y claro. La versión del encabezado de HTTP mantiene las URL limpias pero agrega complejidad, mientras que la versión del parámetro de la consulta generalmente debe evitarse. Mantenga la documentación de la versión clara, pruebe las versiones de forma exhaustiva y deprecie las versiones antiguas gradualmente. Esta práctica mantiene a sus usuarios de API felices y su base de código mantenible. Relaciones 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 Los olores son míos . Opinión Créditos Fotografía por es Marcus Urbenz Unosplash 
 
 Si programas, eres un diseñador de API. El buen código es modular: cada módulo tiene una API. Si programas, eres un diseñador de API. El buen código es modular: cada módulo tiene una API. Josué Bloch https://hackernoon.com/400-thought-provoking-software-engineering-quotes?embedable=true Este artículo es parte de la 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 es producido en el idioma original de la historia!

Demasiado Largo; Para Leer

Make resilience your competitive advantage

Code Smell 309 - Query Parameter API Versión

Code Smell 309 - Query Parameter API Versión

About Author

COMENTARIOS

ETIQUETAS

ESTE ARTÍCULO FUE PRESENTADO EN

Related Stories

De los foros a los feeds: cómo los algoritmos de las redes sociales influyen en la interacción digital

El modelo Bitcoin UTXO, impulsando un ecosistema único

Una breve introducción a la teoría del cerebro de Boltzmann

La guía completa para una migración exitosa a la nube: estrategias y mejores prácticas

De los foros a los feeds: cómo los algoritmos de las redes sociales influyen en la interacción digital

El modelo Bitcoin UTXO, impulsando un ecosistema único

Una breve introducción a la teoría del cerebro de Boltzmann

La guía completa para una migración exitosa a la nube: estrategias y mejores prácticas

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps