Versionado y deprecación

Qué cambios puedes esperar sin avisar, cómo se anuncia un endpoint que se va a retirar y qué headers te lo dicen.

Construir sobre una API es apostar a que lo que funciona hoy funcione en seis meses. Esta página dice exactamente qué puede cambiar sin avisarte, qué no cambia nunca sin un aviso previo, y cómo te enteras.

La regla en una frase

/api/v1 solo crece. Todo lo que hoy responde va a seguir respondiendo igual: si algo tiene que romperse, vive en /api/v2 y los dos conviven al menos seis meses.

Cambios que puedes esperar sin aviso

Estos son aditivos: no rompen a nadie que ya esté integrado, y ocurren seguido.

• Endpoints nuevos.
• Campos nuevos en una respuesta.
• Parámetros opcionales nuevos.
• Valores nuevos en un campo de tipo enum (un estado nuevo, un tipo de canal nuevo).
• Códigos de error nuevos dentro de un type que ya existe.

Dos consecuencias prácticas para tu integración:

1. No asumas que conoces todos los campos de una respuesta. Ignora los que no uses en vez de fallar. Los schemas del contrato están marcados como abiertos justamente para eso.
2. No hagas un switch exhaustivo sobre un enum sin rama por defecto. Un estado nuevo no debería tumbarte el proceso.

Cambios que nunca ocurren sin ciclo de deprecación

• Quitar un endpoint.
• Quitar o renombrar un campo de una respuesta.
• Renombrar una ruta o un operationId.
• Volver obligatorio un parámetro que era opcional.
• Cambiar el significado de un valor que ya existía.

Cualquiera de estos pasa por el ciclo completo que sigue.

El ciclo de deprecación

Cuando un endpoint se va a retirar, ocurren cuatro cosas antes de que deje de responder:

1. Se marca en el contrato. La operación queda con deprecated: true en openapi.public.json, con la fecha de retiro en x-sunset y con qué usar en su lugar en x-alternative. Si generas tu cliente del contrato, la mayoría de los generadores marcan el método como deprecado y tu editor te lo tacha.

1. Cada respuesta te lo dice. Mientras siga vivo, el endpoint responde normal —no falla, no cambia su cuerpo— pero agrega estos headers:

bash curl -i https://api.met.meteor.com.co/api/v1/... \ -H "Authorization: Bearer met_live_tu_key" # HTTP/1.1 200 OK # Deprecation: true # Sunset: Wed, 01 Jul 2026 00:00:00 GMT # Link: <https://developers.meteor.com.co/guias/versionado.html>; rel="deprecation"; type="text/html"; title="Usa POST /runs"

Si tienes observabilidad sobre tus llamadas salientes, vale la pena registrar una alerta cuando aparezca un Deprecation — es la forma más barata de no enterarte tarde.

1. Queda una entrada en el changelog que explica por qué y a qué migrar.

1. Pasan al menos seis meses entre el anuncio y el retiro.

Cómo saber contra qué versión generaste

El contrato declara su versión en info.version, y esa versión es la misma que encabeza la entrada más reciente del changelog.

curl -s https://developers.meteor.com.co/public/openapi.public.json | jq .info.version

Si guardas ese número el día que generas tu cliente, comparar contra el changelog te dice exactamente qué pasó en el medio.

Lo que este ciclo no cubre

• Los type de error son una lista cerrada de cinco valores y no crecen: authentication_error, invalid_request_error, rate_limit_error, agent_error, api_error. Los code dentro de cada uno sí crecen. Programa contra el type cuando necesites una rama de control, y usa el code para el mensaje. Está todo en Errores, idempotencia y paginación.
• Los límites de tu plan no son contrato de API. El rate limit y la cuota pueden cambiar con tu plan; se leen en los headers de cada respuesta, no se asumen. Ver Límites y cuotas.