Versionado

La versión va en la URL: https://olympus.atharix.com/api/v1/…. Mientras uses v1, el contrato de esta documentación se mantiene.

Cambios compatibles

Estos pueden ocurrir en cualquier momento y sin aviso, así que tu integración debe tolerarlos:

• Campos nuevos en las respuestas. No asumas que conoces todas las claves de un objeto; ignora las que no esperas en vez de fallar.
• Endpoints nuevos.
• Parámetros opcionales nuevos en peticiones existentes.
• Valores nuevos en una lista. Pueden aparecer tipos de identificación o códigos de impuesto que hoy no existen. Trata los valores desconocidos con un camino por defecto en vez de lanzar una excepción.
• Códigos de error nuevos. Tu manejador debe tener una rama “cualquier otro error”.
• Mensajes de error reescritos. message está pensado para personas y puede mejorar; programa contra code, que no cambia.
• Orden de los campos en el JSON.

Cambios incompatibles

Estos no ocurren dentro de v1:

• Quitar o renombrar un campo de una respuesta.
• Quitar un endpoint.
• Hacer obligatorio un campo que era opcional.
• Cambiar el tipo de un campo.
• Cambiar el significado de un código de error o de un estado.
• Cambiar el código HTTP de una respuesta que ya funcionaba.

Cuando algo así haga falta, será en una versión nueva (v2), y v1 seguirá funcionando.

Bajas y avisos

Si un endpoint o un campo de v1 va a retirarse:

1. Se anuncia en el changelog con la fecha de baja.

2. Las respuestas afectadas incluyen la cabecera Deprecation y un enlace en Link:

   Deprecation: Thu, 01 Oct 2026 00:00:00 GMT
   Link: <https://olympus.atharix.com/docs/recursos/changelog/>; rel="deprecation"

3. Hay al menos 6 meses entre el anuncio y la retirada.

Vigila la cabecera Deprecation

Si registras las cabeceras de las respuestas, añade una alerta cuando aparezca Deprecation. Es la forma más barata de enterarte a tiempo sin tener que leer el changelog cada semana.

Versión del esquema

El OpenAPI publicado en /api/v1/openapi.json lleva su propia versión semántica en info.version:

• Parche (1.0.1): correcciones de documentación, sin cambios en la API.
• Menor (1.1.0): campos o endpoints nuevos, compatibles.
• Mayor (2.0.0): cambios incompatibles, que irían en /api/v2/.

Puedes generar tu cliente desde ese esquema: está siempre al día porque se genera del mismo código que sirve la API.