Idempotencia API: o que e e por que importa

O que e idempotencia em APIs e por que importa

Idempotencia em APIs e a propriedade que garante que uma mesma requisicao, executada varias vezes, produza o mesmo resultado que a primeira execucao. Isso e essencial para evitar efeitos colaterais duplicados, como cobrancas em dobro ou registros repetidos, especialmente quando ha falhas de rede e retentativas automaticas. Em termos simples: se o cliente envia a mesma operacao duas vezes, o servidor deve tratar como se fosse uma so.

O conceito vem da matematica, mas na pratica de integracao entre sistemas ele resolve um problema muito concreto. Quando um aplicativo de pagamento envia uma requisicao e nao recebe resposta a tempo, ele tende a reenviar. Sem idempotencia, a segunda tentativa poderia gerar outra cobranca. Com idempotencia, o servidor reconhece o pedido repetido e devolve o resultado original.

Por que idempotencia importa em APIs?

Idempotencia importa porque redes sao instaveis. Uma conexao pode cair no meio de uma transacao, o timeout pode ser curto demais ou o servidor pode processar a requisicao, mas a resposta se perder no caminho. Nessas situacoes, o cliente precisa tentar de novo, mas sem saber se a primeira tentativa foi concluida.

Sem idempotencia, cada nova tentativa pode gerar um efeito colateral novo. Um exemplo classico: uma API de transferencia bancaria. Se o cliente envia a mesma transferencia duas vezes, o saldo seria debitado duas vezes. Com idempotencia, a segunda chamada retorna o comprovante da primeira, sem debitar de novo.

Outro ponto e a consistencia em arquiteturas distribuida. Em sistemas que usam filas e processamento assincrono, mensagens podem ser entregues mais de uma vez. A API idempotente garante que o processamento repetido nao corrompa o estado final do recurso.

Quais metodos HTTP sao idempotentes?

Na pratica, os metodos HTTP mais comuns tem comportamentos diferentes em relacao a idempotencia. O GET e naturalmente idempotente, pois apenas consulta um recurso. O PUT, que substitui um recurso por inteiro, tambem e idempotente, ja que enviar o mesmo payload varias vezes resulta no mesmo estado final.

O DELETE e idempotente por definicao. A primeira chamada remove o recurso; as seguintes podem retornar erro 404, mas o estado final e o mesmo: o recurso nao existe mais. Ja o POST, usado para criar recursos, nao e idempotente. Enviar o mesmo POST duas vezes cria dois registros distintos.

O PATCH, que faz alteracoes parciais, pode ser idempotente ou nao, dependendo da implementacao. Se a operacao for absoluta, como definir um campo para um valor fixo, e idempotente. Se for relativa, como incrementar um contador, nao e.

Como implementar idempotencia na pratica?

A forma mais comum de garantir idempotencia em APIs e usar uma chave de idempotencia. O cliente gera um identificador unico para a operacao e o envia em um cabecalho, como Idempotency-Key. O servidor armazena esse identificador junto com a resposta da primeira execucao.

Se a mesma chave chegar novamente, o servidor retorna a resposta armazenada, sem executar a operacao de novo. Esse padrao e usado por grandes provedores de pagamento, como a Stripe, e por servicos da AWS, conforme documentacao publica.

Na pratica, a implementacao exige uma tabela ou cache com tempo de expiracao, normalmente 24 horas. Tambem e preciso decidir o que fazer quando a mesma chave e usada com payload diferente, o que deve gerar erro para evitar inconsistencias.

Quais problemas a falta de idempotencia causa?

A falta de idempotencia gera duplicidade de dados, cobrancas indevidas e inconsistencia entre sistemas. Um exemplo real: um webhook que notifica sobre um pagamento pode ser entregue mais de uma vez. Se a API que recebe o webhook nao for idempotente, o mesmo pagamento sera processado como se fosse novo.

Outro problema comum e a perda de dados em operacoes de atualizacao. Se um cliente envia um PUT para atualizar um recurso e a resposta se perde, ele reenvia o mesmo PUT. Sem idempotencia, o servidor pode aplicar a atualizacao duas vezes, mas como o payload e o mesmo, o resultado final nao muda. O problema maior esta em operacoes que geram novos recursos ou alteram saldos.

Em integracoes B2B, a falta de idempotencia pode quebrar a confianca entre sistemas. Um pedido de compra enviado duas vezes pode gerar duas faturas, dois envios ou dois cobrancas, causando prejuizo e retrabalho.

Idempotencia e a mesma coisa que seguranca?

Nao. Idempotencia nao e um mecanismo de autenticacao ou autorizacao. Ela trata apenas da repeticao de operacoes, nao de quem pode executa-las. Uma API pode ser idempotente e, ao mesmo tempo, exigir autenticacao por token ou chave de API.

A confusao acontece porque ambos os conceitos envolvem protecao, mas em camadas diferentes. Seguranca protege contra acessos nao autorizados; idempotencia protege contra efeitos colaterais de requisicoes repetidas. Um sistema precisa dos dois para ser robusto.

Na pratica, a chave de idempotencia nao deve ser usada como credencial. Ela e apenas um identificador de operacao, geralmente um UUID, e nao substitui o controle de acesso.

Quando usar chave de idempotencia?

Use chave de idempotencia em operacoes que criam ou alteram recursos e que podem ser repetidas sem o cliente saber. Isso inclui POST de pagamentos, criacao de pedidos, envio de mensagens e qualquer operacao que envolva transacao financeira.

Evite usar em GET, pois consultas nao geram efeitos colaterais. Tambem nao e necessario em PUT ou DELETE, que ja sao idempotentes por natureza, a menos que a implementacao interna tenha efeitos colaterais fora do recurso, como disparar um email.

A regra geral: se a operacao pode causar duplicidade ou efeito colateral nao desejado, adicione uma chave de idempotencia. Se nao, mantenha o metodo HTTP padrao.

Resumo

Idempotencia em APIs garante que a mesma requisicao, repetida varias vezes, produza o mesmo resultado. Ela e essencial para evitar duplicidade, cobrancas em dobro e inconsistencia em integracoes. Metodos GET, PUT e DELETE sao idempotentes por padrao; POST e PATCH exigem cuidado. Para operacoes criticas, use chave de idempotencia e armazene respostas anteriores.

Perguntas frequentes sobre idempotencia em APIs

O que e idempotencia em uma API REST?

Idempotencia em uma API REST e a garantia de que executar a mesma operacao varias vezes produz o mesmo resultado que a primeira execucao. Isso se aplica a metodos como GET, PUT e DELETE, que nao devem gerar efeitos colaterais duplicados quando repetidos.

Qual a diferenca entre idempotente e seguro em HTTP?

Seguro significa que o metodo nao altera o estado do servidor, como GET. Idempotente significa que repetir a mesma requisicao nao muda o resultado final. DELETE e idempotente, mas nao seguro, pois altera o estado ao remover o recurso.

Por que POST nao e idempotente?

POST nao e idempotente porque cada chamada cria um novo recurso. Enviar o mesmo POST duas vezes gera dois registros distintos. Por isso, operacoes de criacao exigem chave de idempotencia para evitar duplicidade.

Como funciona a chave de idempotencia?

O cliente gera um identificador unico, envia no cabecalho da requisicao e o servidor armazena a resposta da primeira execucao. Se a mesma chave chegar novamente, o servidor retorna a resposta salva, sem executar a operacao de novo.

Quais APIs usam idempotencia na pratica?

Provedores de pagamento como Stripe e plataformas de nuvem como AWS usam idempotencia em suas APIs. A documentacao da AWS, por exemplo, explica que a idempotencia garante que uma solicitacao seja concluida apenas uma vez.

Idempotencia resolve problemas de timeout?

Idempotencia nao resolve timeout, mas resolve a consequencia dele. Se a requisicao foi processada e a resposta se perdeu, o cliente pode reenviar com a mesma chave e obter o resultado original, sem duplicar o efeito.