Versiones y retiro de la API

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

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:

{
  "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:

Fuentes legibles por máquina

• Documento OpenAPI: info.description describe esta política e info.version es la versión actual.
• Índice de la API: su objeto versioning enumera 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.