# Versiones y retiro de la API

> Cómo se versiona la API REST de Endless con el encabezado Endless-Api-Version, qué puede cambiar en una versión y el aviso de retiro de 180 días.

Source: https://endless.okinawa/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. Hoy no hay nada obsoleto.

## Fija una versión

La versión actual es **1.0.0**. Las rutas no llevan versión (`/assets`, no `/v1/assets`).

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

* Solo cuenta la versión mayor: `1` y `1.0.0` significan lo mismo.
* Si omites el encabezado, aceptas la versión actual.
* Cada respuesta trae `Endless-Api-Version` con la versión que la sirvió.
* Una versión mayor que la API no puede servir falla con `400` y `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

Solo se agregan cosas: operaciones nuevas, entradas opcionales nuevas, campos nuevos en las respuestas. Ignora los campos de respuesta que no reconozcas. Quitar una operación o un campo, o cambiar el tipo de un campo, es una versión mayor nueva.

## Obsolescencia

Una operación obsoleta sigue funcionando **al menos 180 días** después de que se publica su primer encabezado `Deprecation`, y su fecha `Sunset` nunca es anterior. Cada respuesta suya trae estas señales:

| Señal                                                                         | Qué te indica                                                    |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Encabezado `Deprecation` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) | La operación es 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 a partir de la especificación |

## Fuentes legibles por máquina

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