API y empresas

Cómo versionar una respuesta cuando cada jurisdicción cambia

Una respuesta agregada necesita distinguir versión de contrato, revisión de datos y estado de cada fuente. Así un cambio municipal no obliga a reinterpretar silenciosamente todo el resultado.

Por Marco Ferreiro ·

Sala de operaciones con cables de datos conectados a puertos independientes sin etiquetas

Una municipalidad cambia su portal, otra agrega un estado y una tercera deja de informar un campo. Si la API agregadora responde siempre con el mismo JSON pero modifica silenciosamente el significado, el consumidor no puede explicar por qué dos consultas equivalentes produjeron conclusiones distintas.

Versionar bien no consiste en incrementar un número ante cualquier novedad. Consiste en identificar qué cambió: el contrato público, la observación de datos, la regla de cobertura o el adaptador de una fuente.

Separá cuatro dimensiones de cambio

Usar una única etiqueta version mezcla conceptos diferentes. Conviene distinguir:

Una nueva columna en un portal municipal puede exigir actualizar su adaptador sin romper el contrato. En cambio, transformar un campo que antes significaba “actas informadas” en “deuda firme” cambia la semántica y no debería pasar inadvertido bajo la misma promesa.

Hacé que cada respuesta pueda explicarse

Además de los resultados, una respuesta auditable puede incluir:

No hace falta exponer nombres internos de servidores, selectores ni cuerpos crudos. La trazabilidad pública debe permitir reconstruir la interpretación sin revelar secretos operativos ni datos personales innecesarios.

Para una fuente que no respondió, conservá un estado explícito. Cambiar de timeout a una lista vacía para preservar un esquema antiguo sería compatible en forma, pero incompatible en significado.

Documentá el contrato con ejemplos verificables

OpenAPI permite describir operaciones, parámetros, respuestas, encabezados y esquemas. Publicar esa descripción ayuda a validar clientes y a revisar diferencias entre versiones, pero el documento tiene que acompañar la conducta real.

Definí qué campos son obligatorios, cuáles pueden ser nulos y cómo deben ignorarse extensiones desconocidas. Incluí ejemplos de respuesta completa, parcial y fallida. Para cada estado, explicá qué puede concluir el consumidor y qué no.

Una adición opcional suele ser más fácil de adoptar que renombrar o reutilizar un campo. Aun así, el criterio de compatibilidad pertenece a la política publicada: algunos consumidores rechazan propiedades desconocidas aunque el productor las considere inocuas. Los tests de contrato con clientes representativos revelan ese riesgo.

Usá HTTP para identificar representaciones

RFC 9110 define validadores como ETag y Last-Modified, además de solicitudes condicionales. Sirven para saber si una representación cambió y evitar transferencias innecesarias. No reemplazan la versión del contrato ni explican por qué cambió una jurisdicción.

Un ETag diferente puede indicar otra representación del mismo recurso; una versión mayor puede indicar que el consumidor debe adaptar su código. Mantener ambas señales evita convertir la caché en un sistema de versionado improvisado.

Cuando el cliente guarda evidencia, debería conservar también el identificador de respuesta y su fecha, no sólo el cuerpo normalizado. Así puede distinguir una consulta nueva de una reinterpretación posterior.

Errores estables, detalles prudentes

RFC 9457 define application/problem+json para comunicar errores HTTP legibles por máquinas mediante campos como type, status, title, detail e instance. Un tipo estable permite que el cliente trate de manera diferente una fuente temporalmente indisponible y una solicitud inválida.

Los detalles no deben filtrar trazas, credenciales ni estructura interna. La especificación advierte que la información de error requiere revisión de seguridad. Para una integración de jurisdicciones, el contrato puede agregar extensiones documentadas —por ejemplo, un código de fuente— sin volcar la respuesta cruda del organismo.

Planificá deprecación y retiro

Cuando una versión dejará de ser recomendada, RFC 9745 estandariza el encabezado Deprecation. Si además existe una fecha en la que dejará de responder, RFC 8594 define Sunset. Son señales para automatización, no sustitutos de una guía de migración.

Una transición responsable incluye:

  1. documentación de diferencias y alternativa disponible;
  2. período de convivencia medido con uso real;
  3. avisos directos a los consumidores afectados;
  4. fecha de cierre sólo cuando pueda sostenerse;
  5. monitoreo de errores antes y después del cambio.

No anuncies un retiro que el servicio no está preparado para cumplir ni elimines una versión basándote sólo en que bajó el tráfico agregado.

Guardá la evidencia que explica el pasado

Si una jurisdicción cambia, preservá una ficha de la modificación: fuente, momento observado, adaptador desplegado, campos afectados, casos de prueba y decisión de compatibilidad. Los datos sensibles pueden quedar protegidos o representados por hashes y fixtures redactados.

La respuesta histórica no debería mutar para adoptar la interpretación actual. Si se reprocesa, generá una revisión nueva y vinculala con la anterior. De ese modo, soporte y auditoría pueden responder si cambió el dato, la fuente o la regla.

La idea central es mantener estable el significado y versionar cada dimensión en su lugar. Así, una jurisdicción puede evolucionar sin obligar a que toda la API cambie a ciegas, y un cambio realmente incompatible se vuelve visible antes de afectar decisiones operativas.

Metodología

Alcance
Diseño de contratos HTTP para respuestas agregadas a partir de fuentes jurisdiccionales que evolucionan de manera independiente.
Unidad de análisis
Una respuesta lógica, su representación pública y los estados individuales producidos por cada adaptador de fuente.
Cobertura
Principios de documentación OpenAPI, semántica HTTP, errores legibles por máquinas y comunicación de deprecación y retiro.

Limitaciones

Fuentes

Preguntas frecuentes

¿Cada cambio en una fuente obliga a publicar una nueva versión de API?

No. Si el contrato y el significado permanecen estables, el cambio puede registrarse como una nueva observación o versión del adaptador. Una incompatibilidad pública requiere otro tratamiento.

¿Qué versión debería guardar el consumidor junto con una respuesta?

Como mínimo, la versión del contrato y la fecha de generación. Para auditoría también conviene conservar revisión de política, identificador de fuente y versión del adaptador que produjo cada estado.

¿Cómo se anuncia el retiro de una versión?

Documentá la alternativa, notificá la deprecación con anticipación y, si habrá una fecha efectiva de cierre, podés usar los mecanismos estandarizados Deprecation y Sunset junto con comunicación directa.

Notas relacionadas