Idempotencia API: o que e e por que importa

Idempotencia em APIs e a propriedade que garante que executar a mesma requisicao varias vezes produza o mesmo efeito que executa-la uma unica vez. Em termos simples, se voce enviar o mesmo pedido duas vezes, o servidor nao deve criar dois recursos nem cobrar duas vezes. Isso importa porque redes falham, clientes perdem conexao e sistemas precisam de retentativas. Sem idempotencia, uma simples queda de internet pode resultar em pagamento duplicado ou pedido gravado em dobro.

Por que idempotencia e importante em APIs?

Idempotencia protege o consumidor da API de erros causados por retentativas automaticas. Imagine que voce envia um POST para criar um pedido e a resposta se perde no caminho. O cliente nao sabe se o pedido foi criado e tenta de novo. Sem idempotencia, o servidor cria dois pedidos identicos. Com idempotencia, a segunda chamada retorna o mesmo resultado da primeira, sem duplicar nada. Bancos e gateways de pagamento usam esse conceito para garantir que apertar "pagar" duas vezes nao resulte em duas cobrancas.

Quais metodos HTTP sao idempotentes?

No protocolo HTTP, GET, PUT, DELETE e HEAD sao idempotentes por definicao. GET apenas le dados, entao repetir nao muda nada. PUT substitui um recurso pelo mesmo conteudo, logo a segunda chamada deixa o estado identico. DELETE remove um recurso; a primeira chamada remove, as seguintes nao encontram mais o recurso, mas o estado final continua o mesmo. POST nao e idempotente, porque foi feito para criar novos recursos a cada chamada. PATCH tambem nao e, pois pode aplicar incrementos, como somar valores.

Como implementar idempotencia em uma API?

A forma mais comum e usar uma chave de idempotencia. O cliente gera um identificador unico (como um UUID) e envia no cabecalho da requisicao, por exemplo Idempotency-Key: 5f4dcc3b5aa765d61d8327deb882cf99. O servidor armazena essa chave junto com a resposta da primeira execucao. Se a mesma chave chegar de novo, o servidor devolve a resposta salva, sem reprocessar. Isso funciona bem em operacoes de pagamento e criacao de recursos. O servidor deve manter o cache da chave por um periodo, geralmente 24 horas.

Diferenca entre idempotencia e seguranca em APIs

Seguranca em HTTP diz respeito a nao alterar o estado do servidor. GET e seguro, PUT nao e seguro, mas ambos sao idempotentes. Idempotencia e sobre o efeito repetido ser o mesmo, nao sobre nao ter efeito. Uma API pode ser segura e nao idempotente? Sim, um GET que incrementa um contador de visualizacoes nao e idempotente, porque cada chamada muda o estado. Mas isso violaria a semantica do GET. Na pratica, metodos seguros devem ser idempotentes, mas a recíproca nao vale.

O que acontece se uma API nao for idempotente?

O problema classico e a duplicacao de recursos. Um sistema de reserva de hotel, por exemplo, se o cliente clicar duas vezes em "reservar" e o servidor nao tratar idempotencia, cria duas reservas. O usuario ve duas cobrancas e precisa cancelar uma. Em sistemas distribuidos, com filas e retentativas, o risco cresce. A AWS documenta que, em suas APIs, a idempotencia garante que uma solicitacao seja concluida apenas uma vez, mesmo se houver retentativas do cliente.

Boas praticas para projetar APIs idempotentes

Use POST para acoes que nao sao naturalmente idempotentes, mas inclua um campo de chave de idempotencia. Documente claramente quais endpoints exigem essa chave. Para PUT e DELETE, garanta que a semantica seja realmente de substituicao ou remocao, sem efeitos colaterais ocultos. Evite contadores ou timestamps dentro de PUT, pois eles quebram a idempotencia. Se precisar de operacoes nao idempotentes, como "adicionar 1 ao estoque", use POST e trate a concorrencia com bloqueios ou versoes.

Resumo

Idempotencia e o que permite que sistemas confiaveis funcionem sob falhas de rede. Sem ela, retentativas viram duplicacoes. Para o consumidor comum, isso significa menos cobrancas indevidas e menos pedidos repetidos. Para quem desenvolve, e uma exigencia de design, nao um luxo.

Perguntas frequentes sobre idempotencia em APIs

Idempotencia e obrigatoria em toda API?

Nao, mas e altamente recomendada em operacoes que criam ou alteram dados. APIs de leitura (GET) nao precisam de tratamento extra. APIs de pagamento e pedidos deveriam implementar por padrao.

Como testar se minha API e idempotente?

Envie a mesma requisicao duas vezes com a mesma chave de idempotencia e verifique se o estado final e identico ao de uma unica chamada. Tambem teste sem chave para ver o comportamento padrao.

Qual a diferenca entre POST e PUT em relacao a idempotencia?

POST cria novos recursos e nao e idempotente. PUT substitui um recurso existente ou cria naquele URI especifico, entao repetir a mesma chamada nao gera duplicata.

O que e uma chave de idempotencia?

E um identificador unico gerado pelo cliente e enviado na requisicao. O servidor o usa para reconhecer retentativas e retornar a resposta original em vez de reprocessar.

Idempotencia resolve problemas de concorrencia?

Nao diretamente. Ela trata retentativas da mesma operacao. Concorrencia envolve duas operacoes diferentes simultaneas, que exigem controles como locks ou optimistic concurrency.