# Versionamento e depreciação — API Torêva

Como a API pública da Torêva muda, e como você fica sabendo antes de quebrar.

## Versão no caminho

A versão é a primeira parte do caminho, depois de `/api/`:

```
https://toreva.com.br/api/v1/status
```

Versão corrente: **v1**.

`/api/...` sem versão é um **apelido da versão estável corrente**. É conveniente
para explorar no terminal, mas o destino dele muda quando uma nova versão vira
estável. **Integre sempre contra `/api/v1/`.**

Toda resposta sob `/api/` traz o cabeçalho `API-Version` com a versão que
efetivamente respondeu:

```
API-Version: v1
```

Se você chamou `/api/status` e leu `API-Version: v1`, o endereço estável
equivalente é `/api/v1/status`.

## O que é mudança compatível

Dentro de uma mesma versão, estas mudanças podem acontecer sem aviso — seu
cliente precisa tolerá-las:

- **Novo campo** num objeto de resposta.
- **Novo endpoint.**
- **Novo valor** em campo de texto livre (`message`, `hint`, `description`).
- **Novo cabeçalho** de resposta.

Escreva o cliente ignorando campo desconhecido. Não valide resposta com schema
fechado (`additionalProperties: false`) contra a nossa API.

## O que é mudança incompatível

Estas nunca acontecem dentro de uma versão. Elas exigem uma versão nova:

- Remover ou renomear campo de resposta.
- Mudar o tipo de um campo.
- Remover endpoint.
- Remover ou renomear um valor de `error.code`.
- Mudar o significado de um código HTTP.

## Como avisamos

Quando uma versão ou um endpoint entra em depreciação, as respostas dele passam
a carregar dois cabeçalhos padronizados:

```
Deprecation: @1788307200
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Link: <https://toreva.com.br/docs/versioning.md>; rel="deprecation"
```

- **`Deprecation`** (RFC 9745) marca *quando a depreciação passou a valer*, como
  data em segundos desde a época, prefixada por `@`. O cabeçalho presente
  significa: continua funcionando, mas já tem substituto.
- **`Sunset`** (RFC 8594) marca *quando o endpoint deixa de responder*, em data
  HTTP. Depois dessa data, a resposta passa a ser `410 Gone` com
  `error.code` igual a `endpoint_sunset`.
- **`Link` com `rel="deprecation"`** aponta para este documento.

Um cliente bem-comportado registra a presença de `Deprecation` e alerta o
responsável; um cliente automático deve tratar `Sunset` como prazo real.

## Prazos

- **Aviso mínimo de 180 dias** entre o `Deprecation` e o `Sunset` de uma versão
  inteira.
- **Aviso mínimo de 90 dias** para um endpoint isolado.
- Durante todo o período, a versão anterior continua respondendo normalmente —
  depreciação não degrada o serviço.
- Falha de segurança é a única exceção: nesse caso o prazo é o menor possível e
  o aviso vai também por e-mail para quem tiver se identificado no `User-Agent`
  ou pelo canal de contato.

## Como acompanhar

- Este documento: <https://toreva.com.br/docs/versioning.md>
- Estado do serviço: <https://toreva.com.br/api/v1/status>
- Descrição formal: <https://toreva.com.br/.well-known/openapi.json>
- Avisos e dúvidas: contato@toreva.com.br

Se você mantém uma integração, mande um `User-Agent` identificável com um
contato. É por ele que conseguimos avisar antes, e não depois.