冪等性 & 条件付きリクエスト

Idempotency-Key: 二重実行なしに書き込みをリトライする

任意の POST、PUT、PATCH、DELETE に Idempotency-Key ヘッダー (200 文字以内の任意の文字列。UUID で構いません) を付けて送ります。24 時間のあいだ、同じキーと同じリクエストは再実行せずに元のレスポンスを Idempotent-Replay: true 付きでリプレイします。同じキーで異なるボディを送ると 409 idempotency_key_reuse で拒否されます。これこそがこの仕組みが捕まえるためのバグです。キーは API キーごとにスコープされます。401、429、5xx のレスポンスは保存されません。これらはリクエストではなくその瞬間の状態を表すからです。

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

一部の書き込みは構造上冪等で、このヘッダーは不要です。すでに監視中のアカウントの購読は何もせず 200 を返し、持っていないものの DELETE は何もせず、Webhook を既存の URL に設定しても既存のシークレットは保持されます。

ETag と If-None-Match

すべての JSON GET は弱い ETag を返します。If-None-Match として送り返すと、変更のないリソースは本文なしの 304 を返すので、繰り返しの確認が安価です。