멱등성 & 조건부 요청

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는 아무 일도 하지 않으며, 웹훅을 이미 설정된 URL로 다시 설정하면 기존 시크릿이 유지됩니다.

ETag와 If-None-Match

모든 JSON GET은 약한 ETag를 담고 있습니다. If-None-Match로 돌려보내면 변경되지 않은 리소스는 본문 없이 304로 응답하므로 반복 확인이 저렴합니다.