Versionado y obsolescencia

La API se versiona en la ruta de la URL. La versión estable en producción es v1:

https://app.syncro.chat/api/v1

Toda integración debe fijar la versión explícitamente en la URL. No hay negociación de versión por header ni una URL "sin versión" que siga a la más reciente — es deliberado: una integración nunca cambia de comportamiento por su cuenta.

Estos cambios solo ocurren en una versión nueva (v2, v3…):

• Eliminar o renombrar un endpoint, un campo de respuesta o un parámetro
• Volver obligatorio un parámetro que era opcional
• Cambiar el tipo de un campo, o el código HTTP devuelto en un caso ya documentado
• Cambiar el significado de un valor existente

Estos cambios son compatibles y pueden ocurrir en v1 sin aviso previo — tu integración debe tolerarlos:

• Agregar un endpoint nuevo
• Agregar un campo nuevo en una respuesta
• Agregar un parámetro opcional
• Agregar un nuevo valor a un enum existente
• Corregir un comportamiento que divergía de la documentación

Cuando un endpoint o una versión queda obsoleto, el aviso viaja en la propia respuesta HTTP, para que un cliente automatizado lo note sin depender del correo o del changelog:

Header	Contenido
Deprecation	Fecha en que la obsolescencia entró en vigor (HTTP-date), según el RFC 9745
Sunset	Fecha en que el recurso deja de responder (HTTP-date), según el RFC 8594
Link	rel="deprecation" apuntando a la documentación de la alternativa

Ejemplo:

HTTP/1.1 200 OK
Deprecation: Wed, 01 Oct 2026 00:00:00 GMT
Sunset: Sun, 01 Mar 2027 00:00:00 GMT
Link: <https://docs.syncro.chat/es/versioning>; rel="deprecation"

Compromisos:

• Al menos 6 meses entre Deprecation y Sunset.
• Una versión completa de la API solo se apaga con al menos 12 meses de aviso.
• La operación obsoleta también se marca con deprecated: true en la especificación OpenAPI, lo que permite detectar el cambio automáticamente en tu CI.
• Nada se elimina sin que exista una alternativa documentada.

• Monitorea los headers Deprecation y Sunset en las respuestas — es el canal más confiable.
• Compara periódicamente la especificación OpenAPI con la versión que integraste; se genera a partir de esta documentación y refleja el estado actual.
• El objeto x-deprecation-policy en la raíz de la especificación apunta a esta página.