Você já clicou duas vezes no botão de confirmação e ficou com medo de ter gerado duas compras? Esse é o tipo de situação que a idempotência HTTP tenta evitar, e na maioria das vezes, ela funciona, mesmo que a gente só perceba quando falha.
Idempotência em requisições HTTP é a propriedade de um método que, quando executado uma ou mais vezes com os mesmos parâmetros, produz o mesmo resultado no servidor, sem efeitos colaterais adicionais. Não importa se você enviou a requisição uma vez ou dez: o estado final do recurso deve ser o mesmo. É uma das garantias mais importantes para quem projeta APIs REST, porque evita que erros de rede ou duplicação de requisições causem estragos.
Quais métodos HTTP são idempotentes?
GET é idempotente?
Sim. Uma requisição GET apenas recupera um recurso. Fazer o mesmo GET duas, três ou cem vezes não altera nada no servidor. O conteúdo pode mudar por causa de atualizações externas, mas a requisição em si não modifica o estado. É o exemplo mais puro de idempotência.
PUT é idempotente?
Sim, por definição. O método PUT substitui um recurso por completo. Se você envia o mesmo payload duas vezes, o resultado é o mesmo, o recurso fica idêntico após a primeira e a segunda chamada. O problema é que, na prática, muitos servidores tratam PUT de forma incremental, o que quebra a promessa. Um PUT bem implementado deve ser substituição, não atualização parcial.
DELETE é idempotente?
Sim, mas com uma ressalva. Após a primeira requisição DELETE, o recurso some. A segunda requisição pode retornar um 404 (não encontrado), mas o estado do servidor continua o mesmo: o recurso continua inexistente. O efeito colateral é zero. Do ponto de vista do cliente, o resultado é consistente.
POST não é idempotente
POST é o método não idempotente mais comum. Cada requisição cria um novo recurso, por exemplo, um novo pedido ou um novo usuário. Se o cliente repetir o POST por engano, o servidor pode gerar dois registros. Por isso, formulários de pagamento e cadastro costumam usar tokens anti-duplicação.
PATCH não é idempotente (em geral)
PATCH aplica uma modificação parcial. A menos que o servidor implemente uma lógica específica para garantir idempotência, duas requisições PATCH com o mesmo payload podem produzir resultados diferentes, por exemplo, incrementar um contador duas vezes em vez de uma.
Qual a diferença entre idempotência e segurança?
Segurança significa que o método não altera o estado do servidor, GET e HEAD são seguros. Idempotência significa que repetir a chamada não muda o resultado final. Um método pode ser seguro e idempotente (GET), ou não seguro mas idempotente (PUT, DELETE). POST não é nem seguro nem idempotente. Entender essa diferença ajuda a escolher o método certo para cada operação.
Por que a idempotência é importante em APIs?
Ela protege o sistema contra duplicação acidental. Em redes instáveis, o cliente pode não receber a confirmação e reenviar a requisição. Se o método for idempotente, o servidor trata a repetição como inofensiva. Se não for, o resultado pode ser um pedido duplicado, uma cobrança em dobro ou um recurso corrompido. Por isso, boas práticas de API recomendam que operações de criação (POST) sejam acompanhadas de um identificador único (idempotency key) para que o servidor detecte e ignore repetições.
Como implementar idempotência em endpoints POST?
A estratégia mais comum é o cliente enviar um cabeçalho Idempotency-Key com um valor único (como um UUID). O servidor armazena essa chave junto com a resposta da primeira requisição. Se o mesmo cabeçalho chegar de novo, o servidor retorna a resposta original sem executar a operação novamente. Serviços como Stripe e PayPal usam esse mecanismo há anos.
FAQ
O que acontece se eu usar POST de forma idempotente?
Nada impede você de implementar um endpoint POST que seja idempotente, mas isso foge da especificação HTTP. O ideal é usar PUT para substituição e POST apenas para criação, com suporte a chave de idempotência.
HEAD é idempotente?
Sim. HEAD funciona como GET, mas retorna apenas os cabeçalhos, sem o corpo da resposta. Como não altera o estado, também é idempotente.
OPTIONS é idempotente?
Sim. O método OPTIONS consulta as opções de comunicação com o recurso e não modifica nada no servidor.
Idempotência garante que a resposta será sempre a mesma?
Não exatamente. O estado final do servidor deve ser o mesmo, mas a resposta pode variar, por exemplo, um DELETE retorna 200 na primeira vez e 404 na segunda. O efeito colateral é que é consistente.
PATCH pode ser idempotente?
Sim, se a operação for definida como substituição de campo ou se o servidor tratar o payload como uma declaração de estado desejado (como no JSON Patch). Mas, por padrão, não é.
Como testar se um endpoint é idempotente?
Envie a mesma requisição duas vezes seguidas e compare o estado do recurso. Se o resultado for o mesmo após ambas, o endpoint é idempotente. Ferramentas como curl ou Postman ajudam nesse teste.
Resumindo: idempotência é uma das garantias mais simples de entender e uma das mais negligenciadas na prática. Escolher o método certo e, quando necessário, implementar chaves de idempotência evita dores de cabeça que aparecem justamente quando a rede falha, ou quando o usuário clica duas vezes.