Quais são as principais estratégias de versionamento de API, e como você faz o deprecate de uma versão?

Question

IT Interview Practice · Accepted Answer

O versionamento permite evoluir uma API com **breaking changes** sem quebrar os clients existentes. Há três estratégias predominantes, mais um processo de deprecação.

## As três estratégias

**1. URI versioning** — a versão fica no path.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Mais simples e mais visível; fácil de rotear, cachear, e testar em um navegador. Desvantagem: tecnicamente viola "a URI identifica um recurso" (o mesmo user agora tem duas URLs). Essa é de longe a escolha mais comum (GitHub, Stripe historicamente).

**2. Custom header versioning** — a versão viaja em um header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Mantém as URLs limpas mas é invisível em um navegador e mais difícil de cachear.

**3. Media-type (content negotiation) versioning** — versão no `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
A mais "RESTful" (a URL do recurso é estável; apenas sua representation é versionada), mas a menos acessível para os consumidores.

## O que conta como breaking

```text
BREAKING      → remover/renomear um campo, mudar um tipo, mudar auth, apertar validação
NON-BREAKING  → adicionar um novo campo opcional, adicionar um novo endpoint, adicionar um valor de enum*
```
Apenas breaking changes precisam de uma nova versão; adicione mudanças non-breaking à versão atual.

## Processo de deprecação

1. **Anuncie** com datas na documentação e no changelog.
2. **Sinalize em runtime** com headers para os clients perceberem programaticamente:
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users/42>; rel="successor-version"
```
3. **Monitore** o uso da versão antiga e entre em contato com os callers restantes.
4. **Faça o sunset** apenas depois que o uso cair perto de zero.

## Por que isso importa

Os entrevistadores perguntam isto para ver se você consegue fazer uma API crescer em produção sem quebrar os clients que dependem dela — uma preocupação operacional real, não teórica. As respostas mais fortes fazem duas distinções: primeiro, que **a maioria das mudanças é non-breaking** e não deveria disparar um bump de versão de forma alguma (mudanças aditivas vão para a versão atual), reservando o versionamento para breaking changes genuínas; e segundo, que a *estratégia* importa menos que o *processo* — um cronograma de deprecação claro com headers `Deprecation`/`Sunset` e monitoramento de uso é o que de fato protege os consumidores. O URI versioning vence na prática por sua visibilidade e suporte de tooling, mas conhecer os trade-offs (header e media-type mantêm as URLs estáveis e são mais RESTful, ao custo da descoberta) mostra que você entende o espaço de design em vez de apenas imitar `/v1/` por hábito.

As três estratégias

O que conta como breaking

Processo de deprecação

Por que isso importa

Perguntas relacionadas