Idempotence & requêtes conditionnelles

Idempotency-Key : réessayer une écriture sans l'exécuter deux fois

Envoyez un en-tête Idempotency-Key (n'importe quelle chaîne jusqu'à 200 caractères, un UUID convient) sur tout POST, PUT, PATCH ou DELETE. Pendant 24 heures, la même clé avec la même requête rejoue la réponse d'origine, marquée Idempotent-Replay: true, sans agir à nouveau. La même clé avec un corps différent est refusée avec 409 idempotency_key_reuse, ce qui est précisément le bogue qu'elle existe pour attraper. Les clés sont propres à votre clé d'API. Les réponses 401, 429 et 5xx ne sont jamais stockées : elles décrivent l'instant, pas la requête.

curl -X POST https://api.xsignalfeed.com/v1/keywords \
  -H "Authorization: Bearer xsf_your_key" -H "Idempotency-Key: 6f1c0c8e-add-solana" \
  -H "Content-Type: application/json" -d '{"query": "$SOL -filter:retweets"}'
# 201 the first time; the retry returns the same 201 body with Idempotent-Replay: true

Certaines écritures sont idempotentes par construction et n'ont pas besoin de l'en-tête : s'abonner à un compte déjà surveillé ne fait rien et répond 200 ; le DELETE de quelque chose que vous n'avez pas ne fait rien ; régler le webhook sur l'URL qu'il a déjà conserve le secret existant.

ETag et If-None-Match

Chaque GET JSON porte un ETag faible. Renvoyez-le en If-None-Match et une ressource inchangée répond 304 sans corps — peu coûteux à vérifier régulièrement.