Cambiar de versión de API sin perder de vista el flujo de datos
Al cambiar de API deben encajar los sistemas que la llaman, el significado de los datos y las respuestas. Un caso de prueba concreto permite comprobar el cambio.
Planifique el cambio de una interfaz de programación de aplicaciones (API) a partir de los flujos de datos afectados. El nuevo punto de conexión es solo una parte de la migración: los campos, los permisos y la interpretación de las respuestas también deben ajustarse al sistema que realiza las llamadas.
Identificar los sistemas afectados
En una empresa ficticia, un portal de clientes y una importación nocturna envían pedidos a la misma API. Migrar solo el portal dejaría atrás al segundo sistema. Registre qué funciones utiliza cada uno y quién puede realizar su migración. Consulte la información de cambios y retirada del proveedor real; un número de versión no establece un plazo de migración universal.
Google AIP-180 distingue la compatibilidad del código fuente, de la transmisión y de la semántica. Esta guía ayuda a examinar los cambios; no garantiza el comportamiento de cualquier API de terceros.
Describir el cambio con un ejemplo rellenado
En nuestro ejemplo, la solicitud antigua contiene texto en el campo delivery_note. La nueva versión espera el texto en delivery_note.text. Ambas deben transmitir la misma instrucción de entrega: «Tor B». Por tanto, sustituir una URL o establecer la conexión no basta para realizar la migración.
Comprobación | Decisión en el ejemplo |
|---|---|
¿Qué debe conservarse? | Instrucción de entrega Tor B en el pedido correcto |
¿Qué cambia técnicamente? | El campo de texto pasa a una estructura anidada |
¿Qué se considera éxito? | El pedido de destino contiene la instrucción sin cambios |
¿Qué hacer si falta el texto? | Crear el pedido sin instrucción de entrega, como antes |
Compruebe también cómo se comunican los errores y el procesamiento aún en curso. Una estructura de respuesta diferente puede afectar al sistema que llama, aunque la solicitud siga aceptándose.
Comparar las versiones en las mismas condiciones
En un entorno de pruebas adecuado, prepare un pedido normal y otro caso sin instrucción de entrega. Compare los datos guardados en destino y la respuesta visible. Aclare también si los permisos de acceso utilizados cubren ambas versiones. Para esta comparación, no deben enviarse pedidos reales por dos rutas de producción.
Coordinar el cambio con las operaciones abiertas
Defina a partir de qué punto las nuevas solicitudes utilizarán la nueva ruta. Las solicitudes ya enviadas pero aún sin confirmar necesitan una correspondencia para que su repetición no se trate como un pedido nuevo. Acuerde una vuelta a la ruta anterior para las solicitudes nuevas y examine por separado qué ocurre con los datos ya escritos. Restablecer una URL no revierte esos cambios.
La versión antigua puede retirarse de este flujo cuando todos los sistemas identificados hayan migrado y las operaciones abiertas estén relacionadas correctamente. Documente el estado realmente comprobado, además de la nueva etiqueta de versión.
Fuentes
Seguir leyendo
Todos los artículos
APIs e integración con ASES
ERP, CRM y tienda bien conectados