Versões e descontinuação da API

A API REST da Endless em https://api.endless.app é versionada por um cabeçalho da requisição, não pela URL. Nada está descontinuado hoje.

Fixe uma versão

A versão atual é 1.0.0. Os caminhos não têm versão (/assets, não /v1/assets).

Endless-Api-Version: 1

• Só a versão principal conta: 1 e 1.0.0 significam o mesmo.
• Omitir o cabeçalho aceita a versão atual.
• Toda resposta traz Endless-Api-Version com a versão que a atendeu.
• Uma versão principal que a API não atende falha com 400 e 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"
  }
}

O que muda dentro de uma versão principal

Só adições: operações novas, entradas opcionais novas, campos novos nas respostas. Ignore campos de resposta que você não reconhece. Remover uma operação ou um campo, ou mudar o tipo de um campo, é uma nova versão principal.

Descontinuação

Uma operação descontinuada continua funcionando por pelo menos 180 dias depois que o primeiro cabeçalho Deprecation dela é publicado, e a data Sunset nunca é anterior a isso. Toda resposta dela traz estes sinais:

Fontes legíveis por máquina

• Documento OpenAPI: info.description descreve esta política e info.version é a versão atual.
• Índice da API: o objeto versioning lista o cabeçalho, a versão atual, as versões principais aceitas e deprecation_notice_days.
• Referência da API: cada operação, gerada a partir do documento OpenAPI.