Idempotência API: o que é e por que importa

Idempotência em API é a propriedade de uma operação que, executada uma ou várias vezes, produz o mesmo efeito final. Em APIs REST, isso evita duplicidade quando há retentativas por falha de rede, timeout ou reenvio do cliente, tornando o comportamento previsível e seguro.

O que significa idempotência, na prática?

Aplicar a mesma operação várias vezes tem o mesmo resultado que aplicá-la uma só vez. Em ciência da computação, o conceito vem da matemática: multiplicar um número por 1 não altera o valor, então essa operação é idempotente. Em APIs, o critério é o efeito no servidor, não a resposta devolvida. Um GET repetido pode retornar dados diferentes se o recurso mudou, mas não altera o estado. Já um POST de pagamento repetido pode gerar duas cobranças, o que caracteriza um problema.

Por que a idempotência importa em APIs?

Redes falham. Um cliente envia uma requisição, não recebe resposta e tenta de novo. Sem idempotência, o servidor pode processar a operação duas vezes. Em sistemas financeiros, de estoque ou de cadastro, isso significa cobrança duplicada, baixa indevida ou registro repetido. A idempotência funciona como um contrato: o cliente pode retentar com segurança, e o servidor sabe reconhecer que aquela operação já foi aplicada. É uma defesa contra duplicidade, não uma garantia de que a resposta será idêntica.

Quais métodos HTTP são idempotentes?

Na especificação HTTP, GET, HEAD, PUT e DELETE são definidos como idempotentes. POST não é. Isso não quer dizer que DELETE nunca falhe: uma segunda chamada pode retornar 404 porque o recurso já não existe, mas o efeito final permanece o mesmo. PATCH depende da semântica adotada e exige cuidado. Vale lembrar que a idempotência do método não é automática: a implementação precisa respeitá-la.

Como garantir idempotência em operações não idempotentes?

O padrão mais usado é a chave de idempotência. O cliente envia um identificador único por operação, geralmente no cabeçalho, e o servidor registra que aquela chave já foi processada. Se a mesma chave chegar de novo, o servidor devolve o resultado anterior em vez de executar outra vez. Provedores de pagamento e serviços de nuvem costumam documentar esse mecanismo. O ponto de atenção é o armazenamento da chave: ela precisa ter validade definida e ser consultada antes de qualquer efeito colateral.

Quais riscos existem ao ignorar a idempotência?

O risco mais direto é a duplicidade silenciosa. Um webhook reenviado, um botão clicado duas vezes ou um retry automático podem criar registros repetidos sem erro aparente. Em integrações entre sistemas, isso costuma aparecer como inconsistência de dados difícil de rastrear. A recomendação é tratar idempotência como requisito de projeto, não como correção posterior, especialmente em operações que movem dinheiro, estoque ou status de pedido.

Em resumo, idempotência em API é o que permite repetir uma operação sem multiplicar seus efeitos. Métodos HTTP ajudam, mas a garantia real vem da implementação, com chave de idempotência e registro do que já foi processado.

FAQ

O que é idempotência em API em uma frase?

É a propriedade que faz uma operação repetida produzir o mesmo efeito final que uma única execução. Isso permite retentativas seguras em caso de falha de rede, timeout ou reenvio do cliente, sem gerar duplicidade de registros, cobranças ou alterações de estado no servidor.

POST é idempotente?

Não. Pela especificação HTTP, POST não é idempotente, porque cada envio pode criar um novo recurso. Para torná-lo seguro em retentativas, a prática comum é usar uma chave de idempotência enviada pelo cliente e verificada pelo servidor antes de aplicar qualquer efeito.

Qual a diferença entre idempotência e segurança de método HTTP?

Idempotência trata do efeito de repetir a operação. Segurança trata de o método não alterar o estado do servidor. GET é seguro e idempotente. DELETE é idempotente, mas não é seguro, porque remove o recurso. São conceitos distintos, definidos separadamente na especificação.

Como implementar chave de idempotência?

O cliente gera um identificador único por operação e o envia, geralmente em cabeçalho. O servidor verifica se a chave já foi processada, registra o resultado e, em caso de repetição, devolve a resposta anterior. A chave precisa de prazo de validade e armazenamento confiável.

O que acontece se eu não usar idempotência?

Retentativas automáticas e reenvios manuais podem duplicar operações. O sintoma típico é registro repetido, cobrança em dobro ou inconsistência entre sistemas, muitas vezes sem erro visível. Corrigir depois costuma ser mais custoso do que projetar a idempotência desde o início.

Idempotência garante que a resposta será sempre igual?

Não. A garantia é sobre o efeito no servidor, não sobre o corpo da resposta. Um GET repetido pode retornar dados atualizados, e um DELETE repetido pode devolver 404. O que se mantém é o estado final do recurso após a operação.