O que você vai aprender com este artigo?
- O que é Idempotência: Conceito e importância da idempotência em APIs.
- Como usar uma chave de idempotência: Práticas para implementação e uso em suas requisições API.
O que é Idempotência?
Idempotência em uma API refere-se à capacidade de executar múltiplas requisições idênticas em um curto período de tempo com a garantia de que apenas uma única requisição será processada com sucesso. Isso é especialmente útil para evitar efeitos colaterais indesejados quando uma mesma requisição é enviada mais de uma vez devido a problemas de rede ou outras falhas.
Por exemplo, imagine que um ecommerce realiza uma requisição para criar uma fatura, mas, devido a uma falha de rede, a mesma requisição é enviada duas vezes com os mesmos dados. Com o uso de uma chave de idempotência, apenas uma das requisições será processada, evitando a duplicação de pedidos.
Como usar uma chave de idempotência?
A chave de idempotência é gerada pelo próprio lojista e deve ser incluída no header da requisição, utilizando o parâmetro Idempotency-Key. As APIs que aceitam esse recurso são
- Criar fatura
- Criar assinatura
- Transferência para Terceiros
- Criar Pedido de Pagamento
- Criar cliente
- Cobrança direta
- Transferir Valor entre contas iugu (NOVO✨)
Se várias requisições forem enviadas com a mesma chave de idempotência no mesmo instante, apenas uma será processada com sucesso. Para as demais, será retornado o erro 409 (Conflito).
Recipe 🧪
Veja, na prática, como montar uma requisição com Chave de Idempotência: