Cuando rompes las APIs sin aviso, rompes la confianza 
 
 TL;DR: Debe versionar sus APIs para evitar romper los clientes existentes cuando realice cambios. TL;DR: Debe versionar sus APIs para evitar romper los clientes existentes cuando realice cambios. Problemas 
 
 
 
 
 
 
 
 
 Aplicaciones de cliente se despliegan Fracaso de la integración La violación del principio de la mínima sorpresa Downtime La confianza quebrada Requiere rollbacks de despliegue Tiempo de desarrollo perdido Degradación de la experiencia del usuario Soluciones 
 
 
 
 
 
 
 
 
 
 
 
 
 Introducción a la versión semántica Introducción a la compatibilidad retroactiva Create deprecation warnings Creación de Roadmaps Uso de la negociación de contenidos Versiones paralelas Comunicar los cambios temprano Desaparece gradualmente las características Documentos que rompen los cambios claramente Comprobar los parámetros deprecados con logging Prueba de nuevas versiones Eliminar la funcionalidad degradada después del atardecer Contexto Cuando se modifican las APIs sin la versión correcta, se crean cambios revolucionarios que afectan a todos los clientes existentes. Usted obliga a los consumidores a actualizar su código de inmediato o enfrentar fallos del sistema. Usted rompe el contrato implícito entre los proveedores de API y los consumidores. El software moderno depende en gran medida de la estabilidad de la API, y la introducción de cambios de brecha sin aviso puede crear fallas en cascada en sistemas dependientes. Hoy es más importante que nunca desde entonces . muchas IAs construyen sus soluciones utilizando la documentación API existente Cuando actualiza una API sin mantener la compatibilidad retroactiva, corre el riesgo de romper todas las aplicaciones que dependen de ella. Esto crea inestabilidad, frustración y correciones costosas para los usuarios. Los clientes a menudo toleran en nuevas funcionalidades, pero nunca un comportamiento estable previamente roto. defectos La versión correcta garantiza transiciones suaves y mantiene la fiabilidad de su sistema. Código de muestreo equivocado 🙂 // user-api-v1.json - Original API response
{
  "id": 317,
  "name": "Mr Nimbus",
  "email": "nimbus@atlantis.com",
  "nationalities": "Brazilian,Canadian,Oceanic"
}

// Later changed to this without versioning:
{
  "userId": 317,
  "fullName": "Mr Nimbus", 
  "emailAddress": "nimbus@atlantis.com",
  "createdAt": "2018-12-09T18:30:00Z",
  "nationalities": ["Brazilian", "Canadian", "Oceanic"]
}

fetch('/api/users/317')
  .then(response => response.json())
  .then(user => {
    // This breaks when API changes field names and data types
    document.getElementById('name').textContent = user.name;
    document.getElementById('email').textContent = user.email;
    // This breaks when nationalities changes from string to array
    document.getElementById('nationalities').textContent 
      = user.nationalities;
  });
 Derecho // user-api-v1.json - Version 1 (maintained)
{
  "id": 317,
  "name": "Mr Nimbus",
  "email": "nimbus@atlantis.com",
  "nationalities": "Brazilian,Canadian,Oceanic"
}

// user-api-v2.json - Version 2 
// (new structure, backward compatible)
{
  "id": 317,
  "userId": 317,
  "name": "Mr Nimbus",
  "fullName": "Mr Nimbus",
  "email": "nimbus@atlantis.com",
  "emailAddress": "nimbus@atlantis.com",
  "createdAt": "2018-12-09T18:30:00Z",
  "nationalities": "Brazilian,Canadian,Oceanic"
  "nationalitiesList": ["Brazilian", "Canadian", "Oceanic"]
}

// user-api-v3.json - Version 3 
// (new structure, backward not compatible)
{
  "userId": 317,
  "fullName": "Mr Nimbus",
  "emailAddress": "nimbus@atlantis.com",
  "createdAt": "2018-12-09T18:30:00Z",
  "nationalitiesList": ["Brazilian", "Canadian", "Oceanic"]
}

// client-code-versioned.js
const API_VERSION = 'v1';

fetch(`/api/${API_VERSION}/users/317`)
  .then(response => response.json())
  .then(user => {
    document.getElementById('name').textContent = user.name;
    document.getElementById('email').textContent = user.email;
    // V1 handles comma-separated string
    document.getElementById('nationalities').textContent
      = user.nationalities;
  });

// Or with content negotiation
fetch('/api/users/317', {
  headers: {
    'Accept': 'application/vnd.api+json;version=1'
  }
})
  .then(response => response.json())
  .then(user => {
    document.getElementById('name').textContent = user.name;
    document.getElementById('email').textContent = user.email;
    document.getElementById('nationalities').textContent 
      = user.nationalities;
  });
 Detección 
 
 [x] Semi-automático Puede detectar este olor cuando encuentra APIs que cambian nombres de campos, eliminan campos o alteran estructuras de datos sin mantener la compatibilidad retroactiva. Busque aplicaciones cliente que se interrumpan después de las implementaciones de la API. Compruebe los encabezados de versiones que faltan o los esquemas de versiones de URL. Monitorear los registros de errores para picos repentinos en fallas del cliente después de las ediciones. Tags ️ 
 
 APIS Nivel 
 
 [x] El Intermedio ¿Por qué es importante la bijeción ️ Debe mantenerse estable entre su contrato de API y las expectativas del cliente. Mapa Cuando rompas esto Al cambiar la API sin versiones, viole el principio fundamental de que los clientes pueden confiar en interfaces consistentes. Bijeción Crea una discrepancia entre lo que los clientes esperan recibir y lo que proporciona su API. Esto rompe la correspondencia uno a uno entre las promesas de API y la entrega de API, lo que lleva a fallos del sistema y pérdida de confianza. Cuando rompe el mapeo entre su API y la lógica de negocio que representa, los clientes no pueden interactuar de manera confiable con su sistema. Esta incompatibilidad conduce a defectos, tiempos de inactividad, falta de confianza y una mala experiencia del usuario. La generación Los generadores de IA a menudo crean este olor cuando se les pide "mejorar" o "actualizar" las APIs existentes. Se centran en hacer la API "mejor" sin considerar la compatibilidad retroactiva. Debe instruir explícitamente las herramientas de IA para mantener los nombres de campo existentes y agregar la versión al hacer cambios. A menudo prefieren el diseño limpio sobre la estabilidad a menos que Dijo lo contrario. explícitamente Detección Los generadores de IA pueden corregir este olor cuando proporciona instrucciones claras sobre las estrategias de versión de API. Debe pedirles que implementen la versión semántica, mantengan la compatibilidad retroactiva y creen rutas de migración para características degradadas. ¡Pruébelo! Recuerda: los asistentes de IA cometen muchos errores 
 
 Prompt sugerido: Crear la versión de la API para evitar cambios Prompt sugerido: Crear la versión de la API para evitar cambios 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 Without Proper Instructions 
 With Specific Instructions 
 
 
 
 ChatGPT 
 ChatGPT 
 
 
 
 Claude 
 Claude 
 
 
 
 Perplexity 
 Perplexity 
 
 
 
 Copilot 
 Copilot 
 
 
 
 Gemini 
 Gemini 
 
 
 
 DeepSeek 
 DeepSeek 
 
 
 
 Meta AI 
 Meta AI 
 
 
 
 Grok 
 Grok 
 
 
 
 Qwen 
 Qwen ChatGPT ChatGPT Claude Claude Perplejidad Perplejidad piloto piloto Gemini Gemini profundidad profundidad El objetivo es El objetivo es Grúas Grok Quien Quien Conclusión Siempre debe versionar sus APIs para evitar que los cambios de interrupción afecten a las aplicaciones del cliente. Incluso desde su primera versión. Cuando mantiene contratos estables a través de una correcta versión, crea confianza con los consumidores de API y permite una evolución suave de sus sistemas. Los cambios son inevitables, pero no deben romper a sus clientes. Siempre verifique sus APIs, deténgase cuidadosamente y comunique de forma proactiva para evitar interrupciones innecesarias. Relaciones https://hackernoon.com/misusing-http-status-codes-wrecks-your-api-monitoring-and-client-logic https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-iv-7sc3w8n 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-xxii https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxiv https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxv Disclaimer Los olores son míos . Opinión Créditos Fotografía por es Giancarlo Revolledo Unosplash 
 
 Las APIs son para siempre, así que diseñarlas cuidadosamente Las APIs son para siempre, así que diseñarlas cuidadosamente Martin Fowler 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

Código Olor 303 - Cómo evitar la ruptura de los clientes existentes cuando haces cambios

Código Olor 303 - Cómo evitar la ruptura de los clientes existentes cuando haces cambios

About Author

COMENTARIOS

ETIQUETAS

ESTE ARTÍCULO FUE PRESENTADO EN

Related Stories

Toque para ganar: Telegram puede incorporar a los próximos 10 mil millones de usuarios de criptomonedas antes de Solana

¿Quieres ganar un concurso de redacción de HackerNoon? Esto es lo que recomiendan los ganadores del concurso #crypto-api

Valhalla de Floki se une como patrocinador asociado de la gira de la India por Sri Lanka

El modelo Bitcoin UTXO, impulsando un ecosistema único

Toque para ganar: Telegram puede incorporar a los próximos 10 mil millones de usuarios de criptomonedas antes de Solana

¿Quieres ganar un concurso de redacción de HackerNoon? Esto es lo que recomiendan los ganadores del concurso #crypto-api

Valhalla de Floki se une como patrocinador asociado de la gira de la India por Sri Lanka

El modelo Bitcoin UTXO, impulsando un ecosistema único

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps