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

Source: https://endless.app/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. Esta página é a política: como fixar uma versão, o que pode mudar dentro dela e
como uma operação é retirada.

<Callout type="info">
  Nada está descontinuado hoje. Todas as operações da [referência da
  API](/docs/api) estão em vigor.
</Callout>

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

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

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

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](https://www.rfc-editor.org/rfc/rfc9745)) | Que a operação está descontinuada, e desde quando         |
| Cabeçalho `Sunset` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594))      | 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`](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/`](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](/docs/api), gerada a partir do documento OpenAPI (em
  inglês).