Idempotency & koşullu istekler

Idempotency-Key: bir yazmayı iki kez yapmadan yeniden deneyin

Herhangi bir POST, PUT, PATCH veya DELETE isteğinde bir Idempotency-Key başlığı gönderin (200 karaktere kadar herhangi bir dize; UUID uygundur). 24 saat boyunca aynı anahtar, aynı istekle özgün yanıtı Idempotent-Replay: true ile işaretlenmiş olarak, yeniden işlem yapmadan oynatır. Aynı anahtar farklı bir gövdeyle 409 idempotency_key_reuse ile reddedilir; zaten yakalamak için var olduğu hata budur. Anahtarlar API anahtarınıza özeldir. 401, 429 ve 5xx yanıtları asla saklanmaz: bunlar isteği değil, o anı tanımlar.

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

Bazı yazma işlemleri yapıları gereği idempotenttir ve başlığa ihtiyaç duymaz: zaten izlediğiniz bir hesaba abone olmak hiçbir şey yapmaz ve 200 döndürür; sahip olmadığınız bir şeyin DELETE edilmesi hiçbir şey yapmaz; webhook'u zaten sahip olduğu URL'ye ayarlamak mevcut gizli anahtarı korur.

ETag ve If-None-Match

Her JSON GET zayıf bir ETag taşır. Bunu If-None-Match olarak geri gönderin; değişmemiş bir kaynak gövdesiz 304 yanıtı verir — tekrar tekrar kontrol etmek ucuzdur.