🔄

Idempotência

Uma operação é idempotente quando executá-la várias vezes produz o mesmo resultado que executá-la uma única vez. É essencial para sistemas distribuídos confiáveis.

🛗Analogia

O Botão do Elevador

Você aperta o botão do elevador uma vez e ele acende. Apertar mais 10 vezes não faz o elevador chegar mais rápido nem chama 10 elevadores. O resultado é sempre o mesmo: o elevador foi chamado.

💡Conceito

Operações Seguras para Retry

Em sistemas distribuídos, requisições podem falhar ou duplicar. Se a operação é idempotente, podemos fazer retry com segurança — não importa se executou 1 ou 5 vezes, o efeito é o mesmo.

💡Conceito

Idempotency Keys

Uma chave de idempotência é um identificador único enviado pelo cliente. O servidor usa essa chave para detectar duplicatas e retornar o mesmo resultado sem processar novamente.

🔧Exemplo

Pagamento com Chave de Idempotência

Ao processar um pagamento, o cliente envia uma chave única. Se a requisição for repetida (timeout, retry), o servidor reconhece a chave e retorna o resultado anterior sem cobrar duas vezes.

// Cliente envia chave única
const response = await fetch('/api/pagamentos', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'pedido-123-tentativa-abc',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ valor: 99.90, cartao: '****1234' })
});

// Servidor verifica duplicata
async function processarPagamento(req) {
  const chave = req.headers['idempotency-key'];
  const existente = await cache.get(chave);
  if (existente) return existente; // já processou, retorna mesmo resultado

  const resultado = await gateway.cobrar(req.body);
  await cache.set(chave, resultado, { ttl: '24h' });
  return resultado;
}

💡Conceito

POST vs PUT: Quem é Idempotente?

PUT é naturalmente idempotente: atualizar um recurso para o mesmo valor várias vezes não muda nada. POST cria recursos novos a cada chamada — por isso precisa de idempotency keys para ser seguro.

⏰Analogia

Definir o Alarme vs Enviar Mensagem

Definir o alarme para 7h é idempotente: fazer isso 3 vezes resulta em um alarme às 7h. Enviar uma mensagem não é: fazer 3 vezes resulta em 3 mensagens. No mundo das APIs, PUT é o alarme e POST é a mensagem.