Uma equipe altera o significado de um campo e outra descobre o problema quando o aplicativo começa a apresentar dados incorretos. A API continua respondendo, mas o acordo entre os sistemas mudou. Um contrato claro precisa descrever comportamento, além de caminhos e formatos.
Documente o significado dos dados
Informe quais campos são obrigatórios, quais podem ficar ausentes e o que um valor vazio representa. Defina unidades, fusos de horário, identificadores e valores possíveis para estados. Se um preço usa centavos inteiros, essa regra deve estar explícita para todos os consumidores.
Inclua exemplos com situações reais, sem dados privados. Uma resposta preenchida mostra o caminho comum; casos com listas vazias, campos opcionais e recusas ajudam a entender as bordas do contrato.
Explique erros e limites
Quem integra precisa saber distinguir entrada inválida, falta de autorização e indisponibilidade temporária. Um código estável para o tipo de erro facilita o tratamento; a mensagem pode explicar o que aconteceu sem expor detalhes internos.
- Como funcionam paginação e ordenação?
- Qual é o tamanho máximo aceito em um envio?
- Que operações podem ser repetidas com segurança?
- O que acontece quando uma credencial perde validade?
Use uma descrição que acompanhe o código
O OpenAPI oferece uma especificação para descrever interfaces HTTP. Um documento nesse formato pode apoiar documentação e ferramentas de validação. Porém, ele precisa corresponder ao comportamento entregue: manter uma descrição antiga ao lado de uma API nova cria uma segunda fonte de confusão.
Revise o contrato junto com a implementação e valide exemplos e respostas importantes. Registre regras de negócio que não cabem apenas na definição dos campos.
Avalie compatibilidade pela visão do consumidor
Remover um campo ou passar a exigir um parâmetro pode interromper um cliente existente. Acrescentar um valor a uma lista de estados também merece atenção quando o consumidor rejeita valores desconhecidos. Até uma mudança de ordenação pode alterar um fluxo que dependia da resposta anterior.
Para mudanças incompatíveis, combine uma transição: ofereça o contrato novo, comunique o prazo e acompanhe quem ainda usa o anterior. Evite escolher uma estratégia de versionamento sem entender como os clientes serão atualizados.
Teste o acordo entre as equipes
Verifique cenários representativos de quem produz e de quem consome a API. Os testes devem detectar uma mudança que altere o resultado esperado, não apenas confirmar que uma resposta veio com sucesso. Assim, a evolução pode acontecer com uma conversa concreta sobre impacto.
Leitura complementar: especificação oficial OpenAPI.
