A idempotência é um conceito importante em sistemas distribuídos e em APIs web. Uma operação idempotente é aquela que pode ser repetida várias vezes e sempre produzirá o mesmo resultado, independentemente do número de vezes que for chamada. Isso é particularmente crucial em ambientes onde chamadas de API podem ser repetidas devido a falhas de rede, timeouts ou outros problemas.

​
Quando e por que usar

  • Falhas de rede: Quando uma requisição não recebe resposta devido a um erro de rede, a idempotência permite que a mesma seja reenviada sem o risco de duplicar a operação.
  • Prevenção de duplicações: Em cenários onde a mesma operação pode ser enviada mais de uma vez, a idempotência evita resultados duplicados ou inconsistentes.
  • Operações seguras para retentativas: Especificamente útil para operações que modificam dados ou estados (como POST, ou PUT em APIs web).

​
Como funciona

Geralmente, a idempotência em APIs é gerenciada por meio do uso de identificadores únicos para cada requisição. Na Base39, utilizamos chaves de idempotência como identificador único. Ao realizar uma requisição que deseja garantir a idempotência, é necessário fornecer a chave de idempotência (Idempotency-Key) no header da requisição.

​
Melhores práticas

  • Geração de chaves únicas: As chaves de idempotência (Idempotency-Key) devem ser únicas. Recomendamos o uso de UUIDs, ou métodos similares para garantir a unicidade.
    A geração e o gerenciamento das chaves de idempotência são responsabilidades dos nossos clientes e não da Base39.
  • Validade temporal: Para melhor gerenciamento, as chaves de idempotência possuem um período de validade (24h), após o qual uma nova operação com a mesma chave será tratada como distinta.

​
Limitações e considerações

  • Operações não-aplicáveis: Nem todas as operações necessitam de idempotência. Geralmente, requisições GET, que são naturalmente idempotentes, não precisam de idempotência.

​
Comportamentos esperados e possíveis cenários

​
Reenviar uma operação bem-sucedida

Suponhamos que você não tem certeza se sua primeira requisição foi bem-sucedida devido a problemas de rede e decide reenviá-la em um intervalo de 24 horas com a mesma chave de idempotência. Nesse caso, o serviço reconhece de forma inteligente que a operação anterior com essa chave já foi concluída com sucesso e simplesmente retorna o resultado daquela primeira operação bem-sucedida. Não há risco de duplicação.

​
Retentativa após uma falha

Se a sua primeira tentativa falhou e você decide tentar novamente com a mesma chave, o serviço permite essa nova tentativa. A resposta desta tentativa refletirá o sucesso ou falha desta nova operação, como se fosse a primeira vez.

​
Operação em andamento

Digamos que você reenvie uma requisição com a mesma chave enquanto a primeira ainda está sendo processada. Neste caso, para evitar conflitos e duplicações, o serviço de idempotência retorna um erro específico, o erro HTTP 409 (Conflito). Isso indica que uma operação com essa chave já está em andamento, e você deve aguardar a sua conclusão antes de tentar novamente.

​
Utilizar a mesma chave após um longo intervalo

Se após um longo intervalo (por exemplo, mais de 24 horas) você usar a mesma chave novamente, o serviço tratará isso como uma nova operação, pois a chave anterior já expirou.
A idempotência só funciona se a chave de idempotência (Idempotency-Key) for incluida na requisição.

​
Endpoints disponíveis

A grande maioria dos nossos endpoints do tipo POST e PUTestão disponíveis para o uso de idempotência. Para certificar-se se o endpoint que você precisa está disponível, consulte a documentação do mesmo e confira no header se a funcionalidade está disponível. Confira abaixo uma lista de endpoints que, no contexto de crédito consignado, podem interessantes de garantir a idempotência: