Clé d'idempotence

Principe général

L'API permet d'associer une clé d'idempotence (idempotency_key) à une annonce (Ride) afin d'éviter de créer plusieurs fois la même annonce en cas de retry côté client (problème réseau, timeout, etc.).

Lors de la création d'une annonce, si une autre annonce non supprimée du même propriétaire (owner) existe déjà avec la même idempotency_key, la création est rejetée avec une erreur métier (idempotency_key_already_used).

Comment utiliser la clé d'idempotence côté client

• Générer une clé d'idempotence unique par tentative fonctionnelle de création d'annonce (par exemple un UUID v4 ou un identifiant de commande interne à votre système ).
• Envoyer cette clé dans le payload de création de l'annonce, dans l'attribut idempotency_key.
• En cas de doute sur le résultat d'un appel (timeout, 5xx, coupure réseau), réexécuter exactement le même appel avec la même idempotency_key :
  • si l'annonce a déjà été créée, l'API retournera une erreur idempotency_key_already_used et aucune nouvelle annonce ne sera créée ;
  • si l'appel initial n'a pas abouti à une création, l'appel de retry créera l'annonce normalement.

Cas particuliers

• Annonce supprimée (state = removed) :
  • une annonce supprimée n'est pas prise en compte dans la vérification d'unicité (voir Ride#ride_with_same_idempotency_key qui ignore les rides removed) ;
  • cela permet, si besoin, de réutiliser une idempotency_key pour recréer une annonce après suppression.