# Versões e descontinuação da API

> Como a API REST da Endless é versionada com o cabeçalho Endless-Api-Version, o que pode mudar em uma versão e o aviso de 180 dias de descontinuação.

Source: https://endless.okinawa/pt/docs/reference/api-versioning

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

```http
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`:

```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"
  }
}
```

## 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:

| Sinal                                                                        | O que indica                                              |
| ---------------------------------------------------------------------------- | --------------------------------------------------------- |
| Cabeçalho `Deprecation` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) | A operação está descontinuada, e desde quando             |
| Cabeçalho `Sunset` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594))      | Quando a operação para 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 |

## Fontes legíveis por máquina

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