Uma API define como um programa pede dados ou uma ação a outro. É assim que um site cria um contacto no CRM, um serviço de pagamentos comunica um resultado ou uma aplicação móvel consulta uma conta. Uma API útil não é apenas uma lista de endereços: é um contrato sobre dados, permissões, erros e mudanças futuras.
Começar pelas ações reais
Identifique os acontecimentos do negócio e os registos de que a integração precisa. Dê nomes claros às operações e devolva apenas a informação necessária. Descreva as entradas aceites, as respostas possíveis e os erros. A documentação e os exemplos devem corresponder ao serviço em funcionamento, não a uma especificação antiga.
A segurança faz parte do contrato
Autentique quem chama e confirme a autorização para cada registo concreto, não apenas o papel geral da pessoa. Limite a frequência dos pedidos e valide todos os dados recebidos. Guarde tokens secretos em servidores de confiança. Registe as operações que alteram dinheiro, permissões ou informações dos clientes.
Prever redes pouco fiáveis
Um pedido pode expirar depois de o outro serviço já ter concluído o trabalho. Torne as escritas importantes idempotentes: repetir o pedido não pode duplicar encomendas ou cobranças. Defina limites de tempo e regras de repetição. Em integrações por eventos, registe tentativas de entrega e permita repetir as que falharam.
Preparar a evolução
Clientes e serviços raramente são atualizados no mesmo instante. Prefira alterações compatíveis, crie versões para mudanças incompatíveis e acompanhe os clientes que ainda dependem do comportamento antigo. Uma API bem mantida permite evoluir o produto sem transformar cada integração num remendo frágil.
