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.

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.

Hoy no hay nada obsoleto. Todas las operaciones de la referencia de la API están vigentes.

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:

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:

{
  "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)	Que la operación está obsoleta, y desde cuándo
Encabezado `Sunset` (RFC 8594)	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. Su info.description expone esta política, e info.version es la versión actual.
Índice de la API: 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, generada a partir del documento OpenAPI (en inglés).