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;/docses el esquema autoritativo. Los dos no se duplican.✅ Esta política está en vigor desde el 2026-09-23. Ese día el prefijo
v1dejó de responder, en un solo despliegue y sin redirección. Los integradores lo recibieron por la carta de migración, con la guíaantes → despuéscompleta.
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.versiones 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-revisiony elETag.info.x-revisiones 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. ElETagdeGET /docs/openapi.jsonidentifica su contenido exacto: haz la petición conIf-None-Matchy un304te 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
- La entrada en el registro, con su etiqueta y su fecha.
- 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. - 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.