Versionado y obsolescencia

IRIS expone un contrato de lectura estable. Este documento establece qué está versionado, cómo se publica un cambio incompatible y por cuánto tiempo una versión obsoleta sigue sirviendo antes de su remoción.

El esquema por campo de cualquier versión es la referencia OpenAPI (Scalar) en vivo e interactiva en /docs — se genera a partir del código en ejecución y siempre está actualizada. Esta página describe la política; /docs es el esquema autoritativo. Los dos no se duplican.

El contrato del prefijo /v1

Cada endpoint del contrato de lectura vive bajo un prefijo de versión en la URL, p. ej. https://<iris-host>/v1/brands. El prefijo es la versión del contrato: /v1 denota la primera versión mayor estable del contrato REST, y el servidor MCP expone el catálogo de herramientas correspondiente para la misma versión.

Dentro de una versión publicada (/v1) solo hacemos cambios retrocompatibles:

• Agregar un nuevo endpoint.
• Agregar un nuevo parámetro de solicitud opcional.
• Agregar un nuevo campo a un objeto de respuesta.
• Agregar un nuevo valor a una enumeración de conjunto abierto donde el contrato ya documenta que el conjunto puede crecer.

Por lo tanto, los integradores deberían tolerar campos de respuesta desconocidos y no asumir que la forma de la respuesta es cerrada — un lector tolerante sigue funcionando a través de adiciones compatibles.

Los cambios incompatibles se publican bajo una nueva versión

Un cambio retro-incompatible nunca se aplica en el lugar sobre /v1. En cambio, se publica bajo un nuevo prefijo de versión (/v2, y así sucesivamente), y /v1 continúa sirviendo sin cambios. Los cambios incompatibles incluyen, por ejemplo:

• Remover o renombrar un endpoint, campo o parámetro.
• Cambiar el tipo, las unidades o el significado de un campo existente.
• Hacer obligatorio un parámetro previamente opcional.
• Cambiar el comportamiento por defecto de una manera que un cliente existente observaría.

Esto permite a un integrador migrar de /v1 a /v2 según su propio calendario en lugar de quedar roto por un despliegue.

Ventana de obsolescencia

Cuando una versión es reemplazada, se declara obsoleta, no se remueve de inmediato:

1. Anuncio. La obsolescencia se anuncia en el changelog, indicando la versión obsoleta, su sucesora y la fecha de remoción.
2. Ventana. La versión obsoleta sigue sirviendo durante una ventana declarada — al menos 90 días desde el anuncio — para que los integradores tengan tiempo de migrar. La ventana puede extenderse; no se acorta por debajo de lo anunciado.
3. Remoción. Una vez que la ventana se cierra, la versión obsoleta puede removerse. Su remoción queda registrada en el changelog.

Como IRIS corre en una única máquina con puesta en marcha manual por el operador (consulta el SLA), el operador también puede contactar directamente a los integradores para coordinar una migración cuando sea necesario.

Dónde vigilar los cambios

• Changelog — cada versión, anuncio de obsolescencia y remoción.
• /docs — la referencia de esquema en vivo, por versión.