Versões e descontinuação da API

Como a API REST da Endless é versionada com o cabeçalho Endless-Api-Version e como uma operação é descontinuada com 180 dias de aviso.

A API REST da Endless em https://api.endless.app é versionada por um cabeçalho da requisição, não pela URL. Esta página é a política: como fixar uma versão, o que pode mudar dentro dela e como uma operação é retirada.

Nada está descontinuado hoje. Todas as operações da referência da API estão em vigor.

Fixe uma versão com o cabeçalho `Endless-Api-Version`

A versão atual é a 1.0.0. Os caminhos não têm segmento de versão (/assets, não /v1/assets). Para se fixar a uma versão principal, envie o cabeçalho:

Endless-Api-Version: 1

Só a versão principal conta. 1 e 1.0.0 são aceitos igualmente e significam o mesmo.
Se você omitir o cabeçalho, aceita a versão atual.
Toda resposta de uma operação da API traz Endless-Api-Version com a versão que a atendeu, para que você possa registrar com qual versão realmente falou.

Uma versão principal que a API não consegue atender é recusada, em vez de respondida num formato que você não espera. A requisição falha com 400 e o 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"
  }
}

O que muda dentro de uma versão principal

Dentro de uma versão principal, as mudanças só acrescentam:

operações novas
entradas opcionais novas
campos novos numa resposta

Remover uma operação ou um campo, ou mudar o tipo de um campo existente, é uma nova versão principal. Escreva seu cliente para ignorar campos de resposta que ele não reconhece. Um campo novo é compatibilidade futura, não um erro.

Como uma descontinuação é anunciada

Uma operação que vai ser retirada avisa isso em toda resposta que envia, então você fica sabendo pelo seu próprio tráfego:

Sinal	O que indica
Cabeçalho `Deprecation` (RFC 9745)	Que a operação está descontinuada, e desde quando
Cabeçalho `Sunset` (RFC 8594)	Quando a operação deixa de funcionar
Cabeçalho `Link` com `rel="deprecation"`	Onde está a nota de migração
`deprecated: true` no documento OpenAPI	O mesmo, para um cliente gerado a partir da especificação

Pelo menos 180 dias de aviso

Uma operação descontinuada continua funcionando por pelo menos 180 dias depois que seu primeiro cabeçalho Deprecation é enviado. A data de Sunset nunca é anterior a esse prazo.

Para perceber uma descontinuação cedo, verifique se as respostas trazem um cabeçalho Deprecation, ou procure no documento OpenAPI operações marcadas com deprecated: true.

Onde a política é publicada para máquinas

Documento OpenAPI: https://api.endless.app/openapi.json. Seu info.description expõe esta política, e info.version é a versão atual.
Índice da API: https://api.endless.app/. Seu objeto versioning lista o cabeçalho, a versão atual, as versões principais suportadas e deprecation_notice_days.
Referência da API: cada operação, gerada a partir do documento OpenAPI (em inglês).