Guia · Uma integração depende de mais do que um endereço e um exemplo de resposta. O contrato precisa explicar o comportamento esperado quando os dados estão corretos, quando faltam informações e quando a operação é interrompida.
Descreva entradas e resultados
Registre campos, tipos, limites e regras de validação. Diferencie ausência de campo, valor vazio e pedido explícito para apagar um dado.
Inclua exemplos que representem o uso real. Uma documentação que mostra apenas o caminho de sucesso deixa decisões relevantes para o momento do incidente.
Trate erros como parte do contrato
Diferencie falha de autenticação, permissão insuficiente, entrada inválida e indisponibilidade temporária. O consumidor precisa saber qual ação tomar em cada caso.
Mensagens devem ajudar o diagnóstico sem expor segredos. Um identificador de operação pode relacionar a resposta aos registros internos.
Defina o efeito da repetição
Uma resposta perdida não demonstra que a operação falhou. Antes de repetir uma cobrança ou criação, o consumidor precisa de um mecanismo para reconciliar o resultado.
A chave de idempotência, quando oferecida pelo contrato, deve ter escopo e prazo claros. Teste a repetição com a mesma entrada e o conflito com uma entrada diferente.
Planeje mudanças e observação
Registre quais alterações preservam os consumidores e quais exigem coordenação. Confirme exemplos e testes contra o contrato efetivamente publicado.
Observe tempo de resposta, falhas e volume com contexto suficiente para investigar problemas. Evite registrar o conteúdo integral de informações sensíveis.
Imagem de capa ilustrativa: Unsplash.
