Clicked Gallery

O que significa uma API idempotente?

Subrayado en un documento técnico real. Explicado por Clicked.

Usado numa frase

The payment gateway endpoint must be fully idempotent to ensure multiple clicks don’t double-charge the card.

O leitor sublinhou uma palavra na documentação. O Clicked explicou o termo técnico «idempotent» em linguagem simples:

Explicado em três níveis

●○○

Overview

▾

Um endpoint de API idempotente produz o mesmo resultado quer você o chame uma vez ou dez, porque requisições idênticas repetidas não criam efeitos duplicados. É a propriedade que impede um clique duplo de virar uma cobrança dupla.

●●○

Detail

▾

O problema que ela resolve é que redes falham no meio da requisição. Se uma chamada de pagamento estoura o tempo limite, o cliente não tem como saber se o servidor a processou, então tenta de novo. Sem idempotência essa retentativa pode cobrar o cartão duas vezes; com ela, tentar de novo é sempre seguro. A implementação padrão é a chave de idempotência: o cliente anexa um ID único, o servidor registra o resultado da primeira execução sob essa chave, e qualquer repetição com a mesma chave recebe a resposta guardada em vez de executar de novo. Alguns métodos HTTP são idempotentes por definição, já que apagar algo duas vezes ainda o deixa apagado, enquanto o POST não é — exatamente por isso as APIs de pagamento pregam chaves nele. Todo aviso de "não clique em enviar duas vezes" numa página de checkout é um sistema admitindo que pulou essa parte.

●●●

Analogy

▾

O botão do elevador. Aperte uma vez ou aperte sete vezes suspirando, e um elevador vem, porque o pedido é registrado uma vez e cada repetição cai no mesmo resultado. Um elevador que despachasse sete cabines seria um endpoint de pagamento sem idempotência.

Explicações de IA podem conter erros · Não é aconselhamento profissional

Os mesmos fatos, outra vibe — Modo slang 😎

●○○

Overview

▾

Idempotente significa "esmague o botão à vontade, só conta uma vez". Chame uma vez e o cartão é cobrado; chame dez vezes porque o wi-fi engasgou e o cartão continua cobrado uma vez. É a diferença entre uma API que você pode repetir e uma API que você teme. 😎

●●○

Detail

▾

Por que existe: a internet é instável. A requisição estoura o tempo, e aí, foi ou não foi? Ninguém sabe. Então os clientes tentam de novo, e retentativas precisam ser inofensivas. A jogada: mandar uma chave de idempotência única com a requisição; o servidor faz o trabalho uma vez, guarda o recibo sob aquela chave e entrega a cada duplicata o mesmo recibo. Curiosidade de especificação: GET, PUT e DELETE são idempotentes por contrato, enquanto o POST famosamente não é — por isso os provedores de pagamento obrigam você a mandar chaves com ele. Todo aviso de "não clique em enviar duas vezes!" que você já viu é uma confissão. 😎

●●●

Analogy

▾

É confirmar presença num casamento cinco vezes porque você está ansioso. O casal não põe cinco pratos na mesa, porque é um lugar, não importa quantas confirmações você mande. Uma API de pagamento deveria tratar os seus cliques de pânico exatamente como esse anfitrião.

Explicações de IA podem conter erros · Não é aconselhamento profissional

Definição formal — O mesmo termo, explicado da forma habitual

Idempotência é a propriedade pela qual múltiplas invocações idênticas de uma operação produzem o mesmo estado do sistema e a mesma resposta que uma única invocação. Na semântica HTTP, GET, PUT e DELETE são definidos como idempotentes, enquanto o POST não é; serviços comumente implementam idempotência para operações não idempotentes por meio de chaves de idempotência fornecidas pelo cliente, sob as quais o resultado da primeira execução é persistido e devolvido para requisições duplicadas subsequentes, tornando as retentativas seguras diante de falhas de rede.

Quer que o Clicked explique termos como «idempotent» direto no seu navegador, até em PDFs?

Adicionar ao Chrome — Grátis

50 explicações grátis · Sem cartão de crédito

Mais da galeria

O que é geração aumentada por recuperação (RAG)?

Faça a IA responder a partir dos seus documentos — primeiro a busca, depois a resposta, com as fontes à vista.

O que são embeddings vetoriais?

Significado transformado em coordenadas — como máquinas encontram o que é parecido sem bater uma única palavra.

Como ler de verdade um artigo científico (sem se afogar)

Faça a leitura rápida com método, quebre o muro de jargão e conserve o que aprendeu — uma sessão, bem feita.

O que são «sinergias»?

Duas empresas fundidas ganhando mais juntas do que separadas — a promessa, a conta, e a versão da loja de donuts.

O que é dívida técnica?

Atalhos e sistemas envelhecendo que mandam a conta para o futuro — principal, juros e pagamento.

O que é uma prova de conhecimento zero (ZKP)?

Provar que algo é verdade sem revelar o porquê — a criptografia por trás da verificação privada.