La versión va en la URL: /api/v1. Dentro de v1 solo se publican cambios compatibles, de modo que una integración en funcionamiento no requiere cambios.

Cambios compatibles

Se publican en v1 sin aviso previo y se registran en el registro de cambios. Una integración debe tolerarlos:

Recursos, operaciones y parámetros opcionales nuevos.
Campos nuevos en las respuestas y en las cargas de webhooks.
Valores nuevos en campos de estado y códigos de error nuevos.
Eventos de webhook nuevos (solo se reciben con suscripción).
Cambios en el texto de los mensajes: las decisiones se toman con error.code, no con error.message.

Cambios incompatibles

Quitar o renombrar un campo, cambiar su tipo o su significado, o volver obligatorio un parámetro se publica como una versión nueva (/api/v2) en paralelo. La versión anterior se mantiene al menos seis meses después del aviso, que se publica en el registro de cambios.

Versiones de los webhooks

Cada entrega lleva version (actualmente 1). Agregar campos a una carga es compatible; quitar o cambiar uno corresponde a la versión 2, con el mismo aviso.

La especificación como contrato

La especificación OpenAPI describe la versión vigente. Las pruebas de Chainlink comparan cada respuesta real con ella antes de publicar un cambio, de modo que la documentación y la API no se separan.