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é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 |
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
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.
Release v2 ─▶ run v1 + v2 together ─▶ migrate consumers ─▶ deprecate v1 ─▶ remove v1
Nunca remova uma versão enquanto o tráfego real ainda a usa. Acompanhe o uso antes de desativar.
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.