Idempotentie & conditionele verzoeken

Idempotency-Key: een schrijfbewerking opnieuw proberen zonder hem twee keer uit te voeren

Stuur een Idempotency-Key-header (een willekeurige string van maximaal 200 tekens, een UUID is prima) mee met elke POST, PUT, PATCH of DELETE. Gedurende 24 uur speelt dezelfde sleutel met hetzelfde verzoek het oorspronkelijke antwoord opnieuw af, gemarkeerd met Idempotent-Replay: true, zonder opnieuw te handelen. Dezelfde sleutel met een andere body wordt geweigerd met 409 idempotency_key_reuse, precies de bug waarvoor hij bestaat. Sleutels zijn gebonden aan uw API-sleutel. 401-, 429- en 5xx-antwoorden worden nooit opgeslagen: ze beschrijven het moment, niet het verzoek.

dezelfde aanroep twee keer — de tweede is gratis

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

Sommige schrijfacties zijn van nature idempotent en hebben de header niet nodig: abonneren op een account dat u al volgt doet niets en antwoordt met 200; een DELETE van iets dat u niet hebt doet niets; de webhook op de URL zetten die hij al heeft behoudt het bestaande geheim.

ETag en If-None-Match

Elke JSON-GET draagt een zwakke ETag. Stuur die terug als If-None-Match en een ongewijzigde resource antwoordt met 304 zonder body — goedkoop om herhaaldelijk te controleren.