Como você faz versão de APIs e mantém compatibilidade retroativa entre serviços?

Question

IT Interview Practice · Accepted Answer

Como os serviços são implantados independentemente, você nunca pode assumir que os chamadores são atualizado em sincronismo. **Versionamento de API** mais **compatibilidade retroativa** permite que os produtores evoluam sem quebrar os consumidores existentes.

## Estratégias de versionamento

| Estratégia | Exemplo |
|---|---|
| Caminho URI | `GET /v2/orders/42` |
| Cabeçalho | `Accept: application/vnd.api.v2+json` |
| Evolução de schema | adicione campos, nunca remova/renomeie |

## Prefira alterações aditivas (sem quebra)

```text
NON-BREAKING (safe):
  ✓ add a new optional field
  ✓ add a new endpoint
  ✓ add a new enum value (if clients tolerate unknowns)

BREAKING (needs a new version):
  ✗ remove or rename a field
  ✗ change a type or make a field required
  ✗ change semantics of an existing field
```

## Protobuf é amigável para isso

```proto
message Order {
  string id = 1;
  double total = 2;
  string currency = 3;  // NEW field 3 — old clients ignore it safely
}
```

Os números de campo, não os nomes, definem o formato de wire, então adicionar campos é retrocompatível.

## Por que isso importa

```text
Release v2 ─▶ run v1 + v2 together ─▶ migrate consumers ─▶ deprecate v1 ─▶ remove v1
```

## Armadilha

Nunca remova uma versão enquanto o tráfego real ainda a usa. Acompanhe o uso antes de desativar.

## Por que isso importa

A implantação independente só funciona se um produtor puder enviar uma alteração sem coordenar a versão de cada consumidor.

Projetar para mudança aditiva e oferecer suporte a versões antigas durante a migração é o que preserva essa independência em vez de forçar atualizações frágeis do tipo big-bang.

Caminho URI	`GET /v2/orders/42`
Cabeçalho	`Accept: application/vnd.api.v2+json`
Evolução de schema	adicione campos, nunca remova/renomeie

Estratégias de versionamento

Prefira alterações aditivas (sem quebra)

Protobuf é amigável para isso

Por que isso importa

Armadilha

Por que isso importa

Perguntas relacionadas