El problema de las claves de API que nunca caducan
Una clave emitida hace años, que nunca se ha rotado y que hoy sigue siendo válida, no es una comodidad. Es un riesgo que nadie ha revisado de verdad en años.
Argumentos a favor de un versionado de API aburrido y estable
Cuando un proveedor anuncia una nueva versión mayor de su API, normalmente está anunciando a cada cliente con una integración existente un proyecto que no pidió. Incluso un cambio incompatible bien comunicado significa que alguien tiene que reservar tiempo para leer una guía de migración, actualizar el manejo de solicitudes o respuestas, probarlo y desplegarlo, en un plazo marcado por la hoja de ruta del proveedor y no por nada que ocurra en el propio producto de ese cliente.
Creemos que la estabilidad de una API merece tratarse como un objetivo de diseño en sí mismo, no como falta de impulso. Una estructura de respuesta, una vez publicada, debería seguir significando lo que significaba cuando un desarrollador empezó a trabajar con ella. Se pueden añadir campos nuevos como añadidos opcionales, igual que la elevación, las amenazas de IP y el detalle de red son extras opcionales que se suman a las respuestas estándar en lugar de reestructurarlas a la fuerza. Lo que no debería ocurrir en silencio es que un campo existente cambie de significado, que un código de estado se reutilice para otra cosa o que una estructura se reorganice bajo el mismo número de versión.
Parte de la razón por la que los cambios incompatibles son tan frecuentes en este sector es que resultan baratos para el proveedor y caros para el cliente, y las dos partes rara vez negocian directamente ese desequilibrio. Publicar un modelo interno más limpio es un logro de ingeniería legítimo para el equipo del proveedor. Se convierte en una carga en el momento en que obliga a cada integración dependiente a cambiar en respuesta, con un calendario que controla el proveedor y no el cliente.
Esto no significa que una API no deba cambiar nunca. Significa que los cambios deberían ser aditivos siempre que sea posible, y que, cuando un cambio incompatible real sea inevitable, debería ser lo bastante raro como para que un cliente pueda confiar en que la estructura con la que trabajó seguirá funcionando meses o años después, y no algo de lo que tenga que defenderse vigilando un registro de cambios. La estabilidad no es lo mismo que el estancamiento. Es la promesa de que el trabajo de integración de hoy no lleva una fecha de caducidad de la que nadie te avisó.
También tenemos un motivo egoísta para mantener esta postura, más allá de la buena relación con los clientes. Cada host compatible que operamos depende de igualar fielmente la estructura de otro proveedor a lo largo del tiempo, lo cual solo funciona si esas estructuras, una vez igualadas, merecen considerarse objetivos estables. Una empresa que trata su propia API como algo desechable, que se rediseña cuando conviene, es una empresa cuyas garantías de compatibilidad tampoco son realmente garantías. La estabilidad tiene que ser un hábito que se aplique en todas partes o en realidad no se aplica en ninguna.
Aquí, aburrido no es una crítica. Una versión de una API que, años después, sigue funcionando exactamente igual que cuando la integraste no es prueba de que nada haya mejorado. Es prueba de que las mejoras se hicieron de formas que no te obligaron a notarlas, que es precisamente el objetivo de una buena disciplina de versionado.