# Versionado y deprecación

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.

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

   | Header | Qué dice |
   |---|---|
   | `Deprecation` | `true`. Este endpoint está deprecado. |
   | `Sunset` | La fecha a partir de la cual deja de responder, en formato HTTP. |
   | `Link` | Enlace a esta página, con la alternativa en el `title`. |

   ```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.

3. **Queda una entrada en el [changelog](../changelog.html)** que explica por qué y a qué migrar.

4. **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](../changelog.html).

```bash
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](errores-e-idempotencia.html).
- **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](limites.html).