Clicked Gallery

O que significa uma API idempotente?

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

Usado numa frase

Engineering Notes · AI Systems

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

Os mesmos fatos, outra vibe — Modo slang 😎

O método Clicked

●○○

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.
●○○

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. 😎

Uma ideia rápida — muitas vezes é tudo de que você precisa.

●●○

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.
●●○

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. 😎

Quer mais? Um clique aprofunda.

●●●

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.
Deepest level reached.
●●●

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.
Deepest level reached.

Conceito novo? Um exemplo do dia a dia faz clicar — novas analogias quando quiser.

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