Contratos de API
Um contrato é uma promessa para código que você não controla e não pode corrigir. É isso que torna as mudanças de API diferentes da refatoração interna: o custo de errar é pago por outra pessoa, em um momento que você não escolhe.
Design
Nomeie recursos como substantivos e deixe que o método carregue o verbo. Modele a coisa, não a tela que atualmente a exibe — uma carga útil moldada em torno da IU de hoje se torna errada na próxima reformulação.
Seja deliberado sobre o que você expõe. Todo campo que você retorna é um campo que você deve continuar retornando. Identificadores internos, versões de linha e detalhes de implementação vazam seu esquema para o código do chamador e o congelam ali.
Torne as operações idempotentes onde o chamador pode repetir, o que é qualquer operação alcançável por uma rede. Forneça ao chamador uma chave de idempotência para qualquer coisa que crie ou cobre, para que uma repetição após um tempo limite não possa duplicá-la.
Retorne um modelo de erro consistente: um código estável legível por máquina, uma mensagem legível por humanos e o campo ao qual uma falha de validação se refere. Os chamadores se ramificam com base no código, então ele faz parte do contrato — alterar um código é uma mudança de quebra, mesmo que a forma permaneça inalterada.
Paginação em toda lista, desde a primeira versão. Um endpoint que retorna tudo funciona até que a tabela cresça e então falha para o cliente com mais dados. Prefira um cursor a um deslocamento quando linhas são inseridas simultaneamente.
O que quebra um chamador
Quebra, independentemente do que a linguagem de esquema permite:
- Remover ou renomear um campo, um endpoint, um método ou um valor de enum.
- Tornar um campo de solicitação opcional em obrigatório, ou restringir o que um campo aceita.
- Alterar um tipo, incluindo de inteiro para string e de valor único para lista.
- Alterar o significado de um campo existente enquanto mantém seu nome e tipo — o pior tipo, porque nada falha ruidosamente e os dados estão silenciosamente errados.
- Adicionar um novo campo obrigatório a uma solicitação.
- Alterar um código de erro ou um status HTTP para uma condição existente.
- Apertar um padrão, ou alterar o que acontece quando um campo é omitido.
Seguro: adicionar um campo de solicitação opcional, adicionar um campo de resposta, adicionar um novo endpoint ou método, adicionar um valor de enum apenas se todo consumidor já tolerar valores desconhecidos — verifique isso em vez de presumir.
Em protobuf, nunca reutilize ou renumere uma tag de campo, e reserve a tag e o nome quando você remover um campo. Uma tag reutilizada decodifica dados antigos no novo campo e os corrompe silenciosamente.
Alterando um contrato com segurança
Adicione antes de remover, e deixe ambos funcionarem por pelo menos um release:
- Adicione o novo campo ou método junto com o antigo.
- Escreva ambos, leia o novo com um fallback para o antigo.
- Migre os consumidores e confirme que cada um se moveu.
- Remova o caminho antigo em um release posterior.
Versione quando o recurso realmente muda de significado, não para cada adição. Uma versão por mudança multiplica a superfície que você deve manter viva.
Ordem de implantação
Código gerado e servidores são implantados separadamente, e a lacuna é onde as interrupções vivem. Implemente primeiro o lado que tolera ambas as formas: consumidores que aceitam o novo campo antes de produtores emiti-lo, produtores que aceitam a nova solicitação antes de chamadores enviá-la.
Quando um esquema é compartilhado através de um gateway, um proxy ou clientes gerados, todo componente no caminho precisa ser regenerado e reimplantado. Um campo adicionado ao serviço, mas não à camada na frente dele, desaparece antes de alcançar o chamador, e os próprios testes do serviço não perceberão.
Verificar
Verifique os consumidores reais antes de alterar uma forma — faça grep nos chamadores em vez de confiar na documentação do contrato.
Teste o contrato em si: um teste que afirma a forma serializada captura uma renomeação acidental que um teste unitário no manipulador perderá completamente.