A resposta curta: se a ligação cair a meio de um pedido, não sabe se ele foi feito. Com o cabeçalho Idempotency-Key, pode repetir o mesmo pedido sem risco de registar, cobrar ou abrir duas vezes: durante 24 horas, o mesmo valor com o mesmo corpo devolve a resposta guardada e nada é feito outra vez.
Como se usa
Gere um valor único para cada operação, por exemplo um UUID, e envie-o num pedido POST. Pode ter até 255 caracteres visíveis. Repita o mesmo valor só quando repetir a mesma operação.
curl https://api.mozout.com/v1/invoices/3127/pay -X POST \
-H "Authorization: Bearer $RLX_API_KEY" \
-H "Idempotency-Key: 0f8fad5b-d9cb-469f-a165-70867728950e"
O que acontece em cada caso
| Situação |
Resposta |
| Primeiro pedido com este valor |
A operação é feita normalmente. |
| Mesmo valor e mesmo corpo |
Devolve a resposta guardada, com o cabeçalho Idempotent-Replayed: true. Nada é feito outra vez. |
| Mesmo valor e outro corpo |
409 idempotency_conflict |
| Mesmo valor, com o primeiro pedido ainda em curso |
409 idempotency_conflict |
O valor fica reservado para cada chave durante 24 horas.
Onde é obrigatória
| Operação |
O que evita |
| POST /v1/domains/register, /renew, /transfer |
Registar, renovar ou transferir o mesmo domínio duas vezes |
| POST /v1/extras/purchase |
Comprar o mesmo certificado ou SiteLock duas vezes |
| POST /v1/invoices/{id}/pay |
Cobrar a mesma factura duas vezes |
| POST /v1/tickets |
Abrir o mesmo pedido de suporte duas vezes |
| POST /v1/servers/{id}/reinstall, /restore |
Reinstalar ou restaurar o servidor duas vezes |
| POST /v1/sms/messages |
Enviar o mesmo SMS duas vezes |
Nas respostas a pedidos de suporte, POST /v1/tickets/{id}/replies, é aconselhada, para que repetir não responda duas vezes.
Depois de uma falha
| 1 |
Não recebeu resposta (tempo esgotado, ligação cortada): repita o pedido com o mesmo valor.
|
|
| 2 |
Recebeu 409 porque o primeiro ainda está em curso: espere um pouco e repita com o mesmo valor.
|
|
| 3 |
Recebeu 409 porque o corpo é outro: se for mesmo uma operação diferente, use um valor novo.
|
|
Onde a chave não protege
|
Pedidos com senha e entrada no cPanel: nas senhas de caixas de e-mail, de bases de dados e de FTP, e na ligação de entrada no cPanel, a Idempotency-Key não tem efeito: repetir o pedido volta a executá-lo, porque a API nunca guarda a senha nem a ligação.
|
| Caso especial |
O que acontece |
| Senha de root de um VPS |
Repetir com a mesma chave não gera outra senha e devolve password a null. A senha só aparece na primeira resposta: guarde-a logo. |
| Hospedagem com 502 |
Se o pedido já tinha seguido para o servidor, a mesma chave devolve esse 502 sem voltar a executar. Confirme o resultado e, para tentar de novo, use outra chave. |
|
Gere a chave antes da primeira tentativa e guarde-a com a operação (por exemplo, na linha da encomenda na sua base de dados). Assim, mesmo que o programa reinicie a meio, a repetição usa o mesmo valor. A ideia geral, para qualquer API, está em tempos de espera, repetições e idempotência.
|
|
Vai pôr o seu programa a comprar ou a pagar pela API? Teste as repetições em Sandbox antes de usar uma chave de Produção.
Ver a página da API
|
PRODUTO RECOMENDADO Hospedagem de sites com cPanel Domínio e SSL incluídos, cópias diárias e o painel que já conhece. desde $6.60/mês (plano de 3 anos, com cupão) Ver planos |
Angola
Brasil
Kenya
Moçambique
Nigeria
Portugal
South Africa
United Kingdom
United States
International
