Diseñar APIs que no rompan a quien las consume
Una API es un contrato. Cambiarlo sin avisar rompe sistemas de terceros que no controlas. Estas son las prácticas que evitan ese costo.
El contrato incluye más de lo que parece
No es solo la lista de rutas. Es también el formato exacto de cada campo, los códigos de error y su significado, el comportamiento ante datos ausentes, los límites de tamaño y frecuencia, y la semántica de cada operación.
Cualquiera de esos elementos puede romper a un consumidor si cambia sin aviso, incluso cuando las rutas siguen siendo las mismas.
Cambios compatibles y cambios que rompen
| Compatible | Rompe |
|---|---|
| Añadir un campo opcional a la respuesta | Eliminar o renombrar un campo |
| Añadir un endpoint nuevo | Cambiar el tipo de dato de un campo |
| Añadir un parámetro opcional | Hacer obligatorio un parámetro que no lo era |
| Relajar una validación | Endurecer una validación existente |
| Añadir un valor a un enumerado de salida | Cambiar el significado de un código de error |
Los consumidores deben programarse para tolerar campos nuevos que no conocen. Si no lo hacen, incluso una adición rompe, y conviene saberlo antes de desplegar.
Versionado y retirada ordenada
Un cambio incompatible exige una versión nueva conviviendo con la anterior durante un periodo anunciado. La retirada se comunica con antelación, se avisa de nuevo a mitad del plazo y se ejecuta en la fecha comprometida.
Retirar una versión sin aviso, aunque esté documentada como obsoleta desde hace meses, genera incidentes que consumen más tiempo del que ahorró la limpieza.
Errores que sirven para depurar
Un error debe indicar qué falló, en qué campo y qué se esperaba. Un mensaje genérico obliga al consumidor a adivinar y multiplica las consultas al equipo de soporte.
Conviene además incluir un identificador de la petición para que, cuando alguien reporte un problema, sea posible localizar el registro exacto en lugar de reconstruirlo por aproximación.
¿Necesita exponer o integrar servicios web?
Escríbanos con el contexto de su organización. Respondemos con criterio técnico, no con un formulario de ventas.
Contactar