Pular para o conteúdo principal

Idempotência

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.

cURL de exemplo
curl --location 'https://api.base39.io/v1/invoices' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Idempotency-Key: c9b82808-b864-45eb-bc40-87b705fc41e0' \
--header 'Authorization: Bearer 4cHD54272jaxwMW2DS6lG1j5SHJqS1NEEEEEEEEE' \
--data '
{
  "type": "pay_off",
  "payer": "comp_65141b68f88ebbf1ec2afb73",
  "beneficiary": "fund_65141b68f88ebbf1ec2afb73",
  "dueDate": "2024-10-10"
}
'

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.

    nota

    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. :::warningA 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: