Saltar a contenido

Versionado y obsolescencia

Tarno expone un contrato de lectura estable. Este documento describe la política: qué se considera un cambio compatible, cómo se publica uno que rompe y cómo se entera un integrador.

El esquema por campo 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.

✅ Esta política está en vigor desde el 2026-09-23. Ese día el prefijo v1 dejó de responder, en un solo despliegue y sin redirección. Los integradores lo recibieron por la carta de migración, con la guía antes → después completa.

El contrato no lleva versión en la URL

No hay v1 ni v2 en la ruta. Un endpoint es https://api.tarno.cl/trademarks, y punto. El contrato se versiona por su registro de cambios, no por su URL:

  • El changelog del contrato es la versión. Cada entrada dice qué cambió, cuándo, y con cuál de sus siete etiquetas: [ADD] añade (una ruta, un campo, un parámetro opcional) · [BEH] cambia el comportamiento (misma forma, otros valores) · [BREAK] rompe · [FIX] corrige un fallo sin cambiar la forma · [INT] cambio interno, sin efecto visible salvo en un fallo · [DATA] se movió el propio corpus (una recuperación, un relleno, una serie corregida) · [WITHDRAWN] una entrada anunciada y retirada antes de salir: el contrato no se movió.
  • El OpenAPI lleva la fecha del contrato en info.version — es un documento fechado, no un número de versión semántico que nadie incrementaba. ⚠ info.version es la fecha de la última tanda cortada del contrato, no un contador de cambios: no se mueve con cada entrada del changelog.
  • Para saber si tienes que releer el documento, lee info.x-revision y el ETag. info.x-revision es la fecha de la entrada más reciente del changelog con efecto visible en el documento (se calcula al construir; no cuentan [INT], [DATA] ni [WITHDRAWN]) y, si falta, el servidor no la pudo calcular: no la supongas. El ETag de GET /docs/openapi.json identifica su contenido exacto: haz la petición con If-None-Match y un 304 te dice que no cambió nada, aunque la fecha no se haya movido.

Un prefijo de versión promete algo que no se puede cumplir con honestidad: que la versión vieja seguirá sirviendo. Mantener dos contratos vivos a la vez duplica el trabajo de cada cambio y, con un solo integrador, no protege a nadie. Se retira.

Evolución aditiva por defecto — y qué se te pide a cambio

La mayoría de los cambios son compatibles y entran sin aviso previo:

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

⚠ Lo que hace segura esa adición es una obligación tuya, y es la única que te pedimos: tienes que ignorar los campos desconocidos (los que no reconozcas). Un cliente que falle al encontrar una clave inesperada, o que valide la respuesta contra un esquema cerrado, se romperá con un cambio que para todos los demás es compatible. Si tu lenguaje lo permite, deserializa con additionalProperties permitido y no asumas que la forma de la respuesta está cerrada.

Lo que rompe es un [BREAK] directo

Un cambio retro-incompatible se aplica en el sitio, se marca [BREAK] en el registro y se avisa. No hay ventana de deprecación, no hay cabecera de versión y no hay dos contratos conviviendo. Cuentan como [BREAK], por ejemplo:

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

Las retiradas son un [BREAK] más: no tienen ni un ciclo ni un calendario propios.

Cómo te enteras

  1. La entrada en el registro, con su etiqueta y su fecha.
  2. Una carta de migración con el mapa completo antes → después: ruta vieja → ruta nueva, campo viejo → campo nuevo, código de error viejo → nuevo. ⭐ Una sola carta, aunque el despliegue consolide varios cambios: trece avisos sueltos son trabajo de ordenar que te trasladamos a ti.
  3. La guía de migración publicada, con una versión pensada para que la siga un asistente de código.

⛔ Lo que esta política NO hace, y por qué

Se escribe en negativo a propósito, para que no se vuelva a proponer como novedad.

mecanismo estado razón
Prefijo de versión en la ruta (v1, v2) retirado prometía dos contratos vivos a la vez; con un integrador es coste sin beneficio
Cabecera de versión de contrato (p. ej. Iris-Version por fecha) descartado misma razón: es la mecánica de ventana con otra ropa
Cabeceras Deprecation / Sunset (RFC 9745 / RFC 8594) anotado como opción futura son el estándar correcto si algún día hay más de un consumidor. Hoy no lo hay, y una ventana que nadie usa es ceremonia
Ventana mínima de 90 días antes de retirar derogado era la política anterior. Ver abajo
Redirección 308 de la ruta vieja a la nueva descartado mantiene viva la ruta vieja, que es justo lo que el corte elimina

Lo que esta página decía antes, y no se borra en silencio. Hasta el 2026-09-20 esta política prometía que «un cambio retro-incompatible nunca se aplica en el lugar sobre v1… se publica bajo un nuevo prefijo de versión (v2)», con una ventana de al menos 90 días. Estuvo vigente y se aplicó de verdad: la consolidación v1.6 completó ese ciclo entero y retiró denominacion / fechaDesde / fechaHasta, con su guía de migración. La política cambió porque el supuesto que la sostenía —varios integradores con calendarios propios— nunca se cumplió.

Dónde vigilar los cambios

  • /docs — la referencia de esquema en vivo, generada del código en ejecución.
  • Changelog del contrato — cada cambio del contrato con su etiqueta y su fecha, del 2026-09-17 en adelante. Es la versión del contrato.

Tarno corre en una única máquina con puesta en marcha manual por el operador (consulta el SLA), así que el operador también puede contactarte directamente para coordinar una migración cuando haga falta.