Lo que nunca cambia en /v1
- Los endpoints, campos, parámetros y encabezados no se eliminan ni se renombran.
- Un campo mantiene su tipo y su formato, y un campo que siempre llegó sigue llegando.
- Una solicitud que funcionaba sigue funcionando: no aparecen campos ni parámetros obligatorios nuevos, ni límites más estrictos en la entrada.
- Los valores de
typede los errores y sus estados HTTP no cambian. - Un endpoint no pasa a exigir otro scope.
La única excepción es un cambio que cierra una vulnerabilidad de seguridad o que exige la ley: puede llegar antes, y el registro de cambios lo anuncia lo antes posible.
Lo que puede aparecer sin aviso
Estos cambios no rompen un cliente escrito según las reglas de abajo, así que llegan a /v1 en cualquier momento y se anotan en el registro de cambios:
- endpoints nuevos, parámetros y campos de solicitud opcionales nuevos;
- campos nuevos en las respuestas y en los eventos de webhooks;
- valores nuevos de enumeraciones en las respuestas, como los estados de pedido;
- tipos de error nuevos, cada uno con su estado HTTP: mirá el catálogo de errores;
- tipos de evento nuevos: un endpoint de webhooks recibe solo los que tiene suscritos.
Obsolescencia
Cuando un endpoint o un campo tiene un reemplazo mejor, se marca como obsoleto en la referencia, y el registro de cambios anuncia el reemplazo. Un endpoint o campo obsoleto sigue funcionando mientras funcione /v1.
Una versión nueva
Un cambio que rompería clientes —eliminar o renombrar algo, cambiar un tipo, una entrada obligatoria nueva— nunca se hace en /v1. Llega como /v2, publicada junto a /v1 con una guía de migración.
/v1 sigue funcionando al menos 12 meses después del lanzamiento de /v2. La fecha en que deja de funcionar se anuncia en el registro de cambios al lanzar /v2, y desde entonces cada respuesta de /v1 lleva los encabezados Deprecation (RFC 9745) y Sunset (RFC 8594) y un enlace al anuncio.
Cómo seguir los cambios
- El registro de cambios lista cada cambio del contrato por fecha; su feed Atom los lleva a tu lector de feeds o al chat de tu equipo.
- La referencia y el archivo OpenAPI describen siempre el contrato actual: regenerá tu cliente desde el archivo para tomar los campos nuevos.