Cómo evitar cambios disruptivos en la API con API Gateway
September 11, 2023
Cuando desarrollas APIs, a veces realizas cambios que podrían causar problemas a los consumidores actuales de la API. Evolucionar tu API sin afectar a los usuarios actuales es esencial; de lo contrario, podrían perder confianza en tu oferta. Es imposible evitar por completo estos problemas, pero puedes minimizar su impacto o detectar algunos cambios críticos antes de que ocurran. Los cambios que rompen la compatibilidad deben identificarse durante la fase de desarrollo, y si ocurren, el API gateway debe manejarlos para garantizar que las aplicaciones cliente no se vean afectadas. En este artículo, exploraremos algunas mejores prácticas y estrategias para prevenir cambios que rompan la API y cómo manejarlos utilizando el API Gateway APISIX.
¿Qué son los cambios que rompen la API?
Los productos de software evolucionan constantemente, y sus APIs no son una excepción. Estas APIs sirven como la interfaz principal a través de la cual los consumidores externos interactúan con tu sistema, reflejando cualquier cambio en el producto. Hay varias razones para estas modificaciones en la API, incluyendo mejoras tecnológicas, cambios en la dirección del negocio, correcciones de errores críticos y más. En términos simples, un cambio que rompe la compatibilidad es cuando modificas tu API y podría causar problemas a las aplicaciones cliente que la utilizan. Algunos de estos cambios son más fáciles de detectar que otros. Aquí hay algunos ejemplos de cambios que rompen la compatibilidad:
- Eliminar un Endpoint: Si tienes un endpoint
GET /usersy decides eliminarlo, cualquier cliente que intente acceder a él recibirá errores. - Cambiar la URL de un Endpoint: Si cambias la URL de un endpoint de
GET /usersaGET /members, cualquier cliente que use la URL antigua enfrentará problemas. - Modificar el Payload de la Solicitud: Si un endpoint espera datos específicos en la solicitud, como
POST /usersesperando{ "name": "John" }, pero cambias el requisito a{ "firstName": "John" }, interrumpirá a los clientes que envían el formato antiguo. - Eliminar o Renombrar Campos en la Respuesta: Si los clientes esperan campos específicos en la respuesta de la API, eliminar o renombrarlos hará que esos clientes fallen. Por ejemplo, cambiar
{ "id": 1, "name": "John" }a{ "id": 1, "fullName": "John Doe" }. - Cambiar Tipos de Datos: Si un campo de la API se espera que sea una cadena y lo cambias a un entero u otro tipo, esto puede romper los clientes. Por ejemplo, cambiar
"age": "25"a"age": 25. - Cambiar Mecanismos de Autenticación: Si cambias de autenticación básica a autenticación basada en tokens sin una transición adecuada, los clientes existentes enfrentarán errores de autenticación.
- Introducir Campos Obligatorios: Si tienes un endpoint como
POST /usersque toma campos opcionales, y de repente haces que uno de esos campos sea obligatorio, los clientes existentes que no envíen ese campo enfrentarán problemas. - Cambiar Formatos de Error: Si los clientes están programados para entender formatos de error específicos, cambiar esos formatos puede llevar a un manejo inadecuado de errores en el lado del cliente.
- Modificar Códigos de Estado HTTP: Cambiar los códigos de estado para ciertas operaciones, como devolver un
200 OKen lugar de un201 Createdpara la creación de recursos, puede confundir a los clientes. - Descontinuar el Soporte para Versiones Antiguas de la API: Si eliminas el soporte para versiones antiguas sin un período de transición adecuado, los clientes que dependen de esas versiones antiguas se romperán.
Cada cambio en la API tiene el potencial de romper una aplicación cliente. Si utilizas un API Gateway como puerta de entrada para todas las APIs backend, el gateway sabe a dónde redirigir la solicitud basándose en un conjunto de reglas definidas en una configuración de ruta, y es el lugar adecuado para manejar cambios que rompen la API. Veamos cómo podemos usar APISIX para identificar algunos cambios en la API.
Validación de esquemas de solicitud y respuesta
Definir esquemas estrictos para tus rutas te permite asegurar que las estructuras de solicitud y respuesta sean las esperadas. Usa el plugin request-validation para validar las solicitudes entrantes y el plugin response-rewrite para reescribir la respuesta de la API basándose en ciertas condiciones.
Registro de logs
APISIX admite varios plugins de registro, como http-logger, elasticsearch-logger, file-logger y más. Configura un logger para almacenar los datos de solicitud y respuesta de la API y analiza los logs regularmente para detectar cambios en los encabezados de solicitud/respuesta, estructuras de payload o cualquier otro patrón inusual.
Monitoreo de rutas y upstreams
Monitorea las rutas que pasan por el gateway. Si una ruta previamente disponible de repente comienza a devolver errores 404, es una señal potencial de que la API ha sufrido un cambio o un endpoint ha sido descontinuado. Habilita la función de verificación de salud de la API para monitorear continuamente la salud general de los nodos upstream. Si uno de los nodos comienza a fallar, respondiendo más rápido o más lento de lo habitual, podría indicar un cambio en el procesamiento del servicio backend subyacente. Integra APISIX con herramientas de monitoreo como Prometheus usando el plugin prometheus. Configura alertas basadas en métricas, como un aumento en la tasa de errores 4xx o 5xx, lo que podría indicar cambios que rompen la API.
Uso de versionado
El versionado de la API es la práctica de gestionar cambios en una API y asegurar que estos cambios se realicen sin interrumpir las aplicaciones consumidoras de la API. Hay varios métodos para configurar el versionado con APISIX, como usar rutas URI, parámetros de consulta, encabezados o seleccionar el tipo de contenido. Por ejemplo, podrías tener direcciones web como /v1/users o /v2/users para mostrar la versión de tu API. Al tener estas versiones, puedes ofrecer más de una opción de tu API, permitiendo que los consumidores decidan cuándo actualizar a la última versión a su propio ritmo. APISIX puede redirigir fácilmente todo el tráfico de vuelta a la versión antigua y estable de la API hasta que resuelvas los problemas en la nueva versión, lo que hace que tus APIs sean compatibles con versiones anteriores. Emplea APISIX para mantener la compatibilidad antigua mientras implementas los nuevos cambios. Si detectas problemas en la nueva versión, el plugin traffic-split permite una rápida reversión.
Avisos de descontinuación
Antes de eliminar o alterar características, márcalas como descontinuadas, dando a los consumidores tiempo suficiente para adaptarse. Con la ayuda de APISIX, podemos configurar la ruta para comunicar su futura descontinuación y su reemplazo. Para ello, APISIX ofrece el plugin response-rewrite.
Integración con control de versiones
Aunque podrías desear que los revisores de las solicitudes de extracción detecten cualquier cambio que rompa la compatibilidad, confiar únicamente en este método no es seguro y podría llevar a fallos eventualmente. Si tienes documentación OpenAPI/Swagger para tus APIs, estas pueden ser controladas por versiones e incluidas en un pipeline de CI. APISIX no admite nativamente la integración directa con sistemas de control de versiones como Git para cambios en las especificaciones de la API. Sin embargo, puedes configurar un proceso fuera de APISIX. Herramientas como Oasdiff o Bump pueden identificar cambios en las especificaciones de la API y activar un pipeline de CI (agrega GitHub Action) que ejecute pruebas contra los endpoints de ruta en APISIX para asegurar que no se introduzcan cambios que rompan la compatibilidad.
Otras formas de detectar cambios
Postman contiene una plantilla para verificar automáticamente la versión actual de tu API en busca de cambios que rompan la compatibilidad y describe cómo funciona en este artículo. Puedes agregar el detector al pipeline de CI como un paso adicional. Cada vez que tu pipeline se ejecute, el detector de cambios que rompen la compatibilidad analizará la especificación actual de la API contra la anterior y te notificará de cualquier diferencia. Dependiendo de tu stack de desarrollo, hay otras bibliotecas para comparar especificaciones OpenAPI. Este artículo explica bien cómo detectarlos en la práctica utilizando estrategias de implementación probadas antes de llevar los nuevos cambios a producción.
Resumen
Detectar y prevenir cambios que rompen la API es importante para mantener la confianza con los consumidores de la API y asegurar el éxito de tu servicio. Al integrar las capacidades de APISIX como la validación de solicitudes, el versionado, el registro, el monitoreo y las alertas con técnicas como las pruebas automatizadas de contratos de API, puedes asegurar que tus APIs evolucionen sin afectar negativamente a tus clientes.