Versionar interfaces: cómo cambiar sin romper

Qué cuenta como cambio que rompe

Quitar un campo o una ruta, cambiar un tipo, hacer obligatorio un campo opcional, cambiar el significado de un valor existente, y endurecer límites. Añadir un campo opcional no rompe, siempre que los consumidores ignoren los campos que no reconocen, una regla que vale la pena documentar.

Cómo gestionar una transición

Ejecuta la versión nueva junto a la vieja, mide quién usa aún la vieja, y apágala solo tras que el uso llegue a cero o hayas dado aviso suficiente.

Pocas versiones con contenido significativo vencen a una versión por cada cambio pequeño. Cada versión viva es código que mantener y probar.

Retirar de forma gradual

Marca campos y rutas como previstos para eliminación en la documentación y en una cabecera de respuesta, con una fecha. Envía un aviso a los consumidores activos. Y por último, antes de apagar: ejecuta una “oscuridad controlada”: apágalo unos minutos y mira quién grita.