# Versiones y retiro de la API

> Cómo se versiona la API REST de Endless con el encabezado Endless-Api-Version y cómo se retira una operación con 180 días de aviso.

Source: https://endless.app/es/docs/reference/api-versioning

La API REST de Endless en `https://api.endless.app` se versiona con un encabezado de la
solicitud, no con la URL. Esta página es la política: cómo fijar una versión, qué puede cambiar
dentro de ella y cómo se retira una operación.

<Callout type="info">
  Hoy no hay nada obsoleto. Todas las operaciones de la [referencia de la
  API](/docs/api) están vigentes.
</Callout>

## Fija una versión con el encabezado `Endless-Api-Version`

La versión actual es la **1.0.0**. Las rutas no llevan un segmento de versión (`/assets`, no
`/v1/assets`). Para fijarte a una versión mayor, envía el encabezado:

```http
Endless-Api-Version: 1
```

* **Solo cuenta la versión mayor.** `1` y `1.0.0` se aceptan por igual y significan lo mismo.
* **Si omites el encabezado**, aceptas la versión actual.
* **Cada respuesta** de una operación de la API incluye `Endless-Api-Version` con la versión que
  la atendió, para que puedas registrar con qué versión hablaste realmente.

Una versión mayor que la API no puede atender se rechaza, en lugar de responderse con una forma
que no esperas. La solicitud falla con `400` y el motivo `unsupported_api_version`:

```json
{
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "This deployment serves API version 1.0.0; the request asked for 2.",
  "data": {
    "code": "unsupported_api_version",
    "hint": "Send `Endless-Api-Version: 1`, or omit the header to accept the current version.",
    "documentation": "https://endless.app/docs/api"
  }
}
```

## Qué cambia dentro de una versión mayor

Dentro de una versión mayor, los cambios **solo agregan**:

* operaciones nuevas
* entradas opcionales nuevas
* campos nuevos en una respuesta

Quitar una operación o un campo, o cambiar el tipo de un campo existente, es una nueva versión
mayor. Escribe tu cliente para que ignore los campos de respuesta que no reconoce. Un campo
nuevo es compatibilidad hacia adelante, no un error.

## Cómo se anuncia una obsolescencia

Una operación que va a retirarse lo indica en cada respuesta que envía, así te enteras por tu
propio tráfico:

| Señal                                                                         | Qué te indica                                              |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Encabezado `Deprecation` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) | Que la operación está obsoleta, y desde cuándo             |
| Encabezado `Sunset` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594))      | Cuándo deja de funcionar la operación                      |
| Encabezado `Link` con `rel="deprecation"`                                     | Dónde está la nota de migración                            |
| `deprecated: true` en el documento OpenAPI                                    | Lo mismo, para un cliente generado desde la especificación |

## Al menos 180 días de aviso

Una operación obsoleta sigue funcionando **al menos 180 días** después de que se envía su
primer encabezado `Deprecation`. La fecha de `Sunset` nunca es anterior a ese plazo.

Para detectar una obsolescencia a tiempo, revisa si las respuestas traen un encabezado
`Deprecation`, o busca en el documento OpenAPI operaciones marcadas con `deprecated: true`.

## Dónde se publica la política para máquinas

* **Documento OpenAPI**: [`https://api.endless.app/openapi.json`](https://api.endless.app/openapi.json).
  Su `info.description` expone esta política, e `info.version` es la versión actual.
* **Índice de la API**: [`https://api.endless.app/`](https://api.endless.app/). Su objeto
  `versioning` lista el encabezado, la versión actual, las versiones mayores admitidas y
  `deprecation_notice_days`.
* **Referencia de la API**: [cada operación](/docs/api), generada a partir del documento OpenAPI
  (en inglés).