Idempotence

Rejouer une création sans jamais la dupliquer.

Le problème

Votre requête part, le réseau tombe, vous ne savez pas si elle est arrivée. Si vous réessayez, vous risquez de prélever le client deux fois. Si vous ne réessayez pas, vous risquez de ne pas l'avoir prélevé du tout. Sur un rail mobile money, où un appel peut mettre plusieurs secondes, ce cas arrive.

La solution

Ajoutez un en-tête Idempotency-Key à toute requête de création. Choisissez une valeur unique par opération métier — un UUID, ou votre propre référence de commande. 

curl -X POST https://maticorp.tech/api/v1/payments \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Idempotency-Key: commande-7f3a91" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "msisdn": "0190000000"}'

Rejouez la même requête avec la même clé : vous recevez la réponse d'origine, telle quelle, et rien n'est créé une seconde fois. La réponse rejouée porte un en-tête qui le dit : 

MaticPay-Idempotent-Replay: true

Même clé, corps différent

Si vous réutilisez une clé avec un corps de requête différent, nous refusons plutôt que de deviner laquelle des deux intentions est la bonne. 

409 Conflict

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Cette clé d'idempotence a déjà été utilisée avec un corps de requête différent.",
    "param": "Idempotency-Key",
    "hint": "Utilisez une nouvelle clé, ou renvoyez exactement le même corps."
  }
}

Où elle s'applique

Les lectures n'en ont pas besoin : elles ne créent rien. L'en-tête est facultatif, mais sur un déboursement il vous évite d'envoyer deux fois la même somme — nous vous recommandons de toujours le poser.