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 entoncesmuchas 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 tolerandefectosen nuevas funcionalidades, pero nunca un comportamiento estable previamente roto.
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": "[email protected]",
"nationalities": "Brazilian,Canadian,Oceanic"
}
// Later changed to this without versioning:
{
"userId": 317,
"fullName": "Mr Nimbus",
"emailAddress": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"emailAddress": "[email protected]",
"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": "[email protected]",
"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 estableMapaentre su contrato de API y las expectativas del cliente.
Cuando rompas estoBijeciónAl cambiar la API sin versiones, viole el principio fundamental de que los clientes pueden confiar en interfaces consistentes.
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 queexplícitamenteDijo lo contrario.
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 |
|---|---|
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/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íosOpinión.
Créditos
Fotografía porGiancarlo RevolledoesUnosplash
Las APIs son para siempre, así que diseñarlas cuidadosamente
Las APIs son para siempre, así que diseñarlas cuidadosamente
Martin Fowler
Este artículo es parte de la serie CodeSmell.
