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
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.