110 lines
11 KiB
Markdown
110 lines
11 KiB
Markdown
---
|
|
title: IETF draft — The Idempotency-Key HTTP Header Field (httpapi WG)
|
|
source_type: official-doc
|
|
url: https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [ca-idempotency, ietf-draft, standard, header-spec]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
related_branches: [feature-rate-limit-idempotency-contract, feature-api-contract-baseline]
|
|
created: 2026-05-22
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# IETF draft — The Idempotency-Key HTTP Header Field
|
|
|
|
> Layer: `raw/official-docs/` — IETF httpapi 워킹그룹의 `Idempotency-Key` HTTP 헤더 표준화 초안. ca-tmpl 의 422/409 status code 선택의 표준 근거.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-rate-limit-idempotency-contract]] | ca-tmpl 의 422 (fingerprint mismatch) / 409 (in-flight) status code 의 표준 근거 + scope 정의 자유 ("resource owner defines") |
|
|
| [[raw/branch-notes/feature-api-contract-baseline]] | `Idempotency-Key` 헤더명 채택의 표준 초안 근거 (vendor-specific 헤더명 회피) |
|
|
| [[raw/project-notes/ca-skeleton-operational-contract]] | §13. API Contract Surface (Idempotency-Key) + §18. Control Plane Contract — 표준 reference |
|
|
|
|
## 컨텍스트
|
|
|
|
ca-tmpl 이 사용하는 422 (fingerprint mismatch) / 409 (in-flight) 상태 코드의 근거를 표준 문서 차원에서 확인. 또한 "scope 는 resource owner 가 정의한다" 는 점이 ca-tmpl triple scope 선택의 정당성 근거가 됨. 정식 RFC 가 아니라 draft 단계이지만 Stripe / PayPal / Square / Adyen 등이 공통 참조하는 사실상의 헤더 표준 초안.
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
|
|
- 보조: latest draft (draft-07, 2025-10) 의 HTML 렌더링
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: IETF httpapi Working Group (Editors: Sanyam Mehra, et al.)
|
|
- 발행일: draft-ietf-httpapi-idempotency-key-header-07 (2025-10)
|
|
- 마지막 확인일: 2026-05-27 (WebFetch 재검증 완료 against draft-07 — 5개 quote 중 4개 verbatim MATCH, 1개 (C1) 는 라이브 본문이 "resource server" 가 아닌 "resource", 2026-05-27 verified 본 추가)
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§Introduction, 2026-05-22 capture — "resource server" 표현, 라이브 본문은 "resource"] "An idempotency key is a unique value generated by the client which the resource server uses to recognize subsequent retries of the same request. The `Idempotency-Key` HTTP request header field carries this key."
|
|
|
|
> [§2, draft-07, 2026-05-27 verified verbatim] "An idempotency key is a unique value generated by the client which the resource uses to recognize subsequent retries of the same request."
|
|
|
|
> [§2.2, draft-07, 2026-05-27 verified — full form] "Uniqueness of the key MUST be defined by the resource owner and MUST be implemented by the clients of the resource."
|
|
|
|
> [§2.7, draft-07, 2026-05-27 verified MATCH] "If there is an attempt to reuse an idempotency key with a different request payload, the resource SHOULD reply with a HTTP `422` status code..."
|
|
|
|
> [§2.6, draft-07, 2026-05-27 verified MATCH] "The request was retried before the original request completed. The resource SHOULD respond with a resource conflict error."
|
|
|
|
> [§2.3, draft-07, 2026-05-27 verified — full sentence] "The resource MAY require time based idempotency keys to be able to purge or delete a key upon its expiry. The resource SHOULD define such expiration policy and publish it in the documentation."
|
|
|
|
> **draft status caveat (2026-05-27)**: 본 quote 들은 draft-ietf-httpapi-idempotency-key-header-**07** (2025-10) 기준 verbatim. IETF draft 는 revision 마다 본문 변경 가능 (draft-08+ 출시 시 재확인 필수). RFC 정식 승급 전 까지는 strength = `official-reference` (정식 standard 아닌 work-in-progress IETF document).
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| IETF-IDEMP-C1 | idempotency key 는 client 가 생성한 unique value 로 resource 가 subsequent retry 를 인식하는 데 사용되며, `Idempotency-Key` HTTP request header field 가 이 key 를 운반 | [§2, draft-07, 2026-05-27 verified] "An idempotency key is a unique value generated by the client which the resource uses to recognize subsequent retries of the same request." | `official-reference` | HTTP API 의 idempotent request 헤더 명명 | RFC 가 아닌 IETF draft — 정식 표준 지위 아님. revision 마다 본문 변경 가능. 2026-05-22 capture 의 "resource server" 는 draft-07 의 "resource" 와 다름 (의미 비등가하지만 draft 진화 과정에서 단순화된 표현) |
|
|
| IETF-IDEMP-C2 | key 의 uniqueness 정의는 resource owner (= server) 가 책임지며 (`MUST`), client 는 이를 구현해야 함 (`MUST`) | [§2.2, draft-07, 2026-05-27 verified] "Uniqueness of the key MUST be defined by the resource owner and MUST be implemented by the clients of the resource." | `official-reference` | scope 정의 (어떤 dimension 으로 unique 한지) | scope 를 반드시 어떤 형태 (pair/triple/body-hash) 로 정의해야 한다는 뜻은 아님 — 자유. draft 상태이므로 정식 RFC 미달 |
|
|
| IETF-IDEMP-C3 | 같은 idempotency key 로 다른 request payload 를 재사용하면 resource 는 HTTP `422` 를 반환해야 함 (`SHOULD`) | [§2.7, draft-07, 2026-05-27 verified] "If there is an attempt to reuse an idempotency key with a different request payload, the resource SHOULD reply with a HTTP `422` status code..." | `official-reference` | server 측 fingerprint mismatch 처리 | `MUST` 가 아닌 `SHOULD` — 다른 status code (예: 400) 사용도 draft 위반은 아님. body 동일성 비교 메커니즘 (hash / 전체 비교) 은 본 인용 범위 밖 |
|
|
| IETF-IDEMP-C4 | original request 가 완료되기 전 재시도된 request 에 대해 resource 는 conflict error (HTTP `409`) 로 응답해야 함 (`SHOULD`) | [§2.6, draft-07, 2026-05-27 verified] "The request was retried before the original request completed. The resource SHOULD respond with a resource conflict error." | `official-reference` | in-flight 동시 요청 처리 | `SHOULD` — wait/poll 동작도 draft 위반은 아님 (ca-tmpl 의 200ms wait 는 다른 선택). client backoff 정책은 인용 범위 밖 |
|
|
| IETF-IDEMP-C5 | resource 는 time-based key expiration 정책을 요구할 수 있고 (`MAY`), 그러한 expiration 정책을 정의하여 문서에 공표해야 함 (`SHOULD`). 표준이 정확한 시간을 정하지는 않음 | [§2.3, draft-07, 2026-05-27 verified] "The resource MAY require time based idempotency keys to be able to purge or delete a key upon its expiry. The resource SHOULD define such expiration policy and publish it in the documentation." | `official-reference` | TTL 정책 (24h / 30일 / 45일 등 vendor 별 자유) | 표준이 권장 TTL 을 정한다는 뜻은 아님. expiration 없이 영구 보존하는 것이 draft 위반이라는 뜻도 아님 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것** (단, IETF draft = work-in-progress 상태):
|
|
- `IETF-IDEMP-C1`: `Idempotency-Key` 헤더명 표준화 시도
|
|
- `IETF-IDEMP-C2`: scope 정의 자유는 server 책임
|
|
- `IETF-IDEMP-C3` ~ `C4`: 422 (fingerprint mismatch) / 409 (in-flight) status code 권장
|
|
- `IETF-IDEMP-C5`: expiration 정책은 server 가 정의하여 문서화
|
|
- **이 자료가 증명하지 않는 것**:
|
|
- 정식 RFC 지위 (draft 상태 — published RFC 가 아님)
|
|
- 모든 vendor 가 이 권장을 따른다는 보장 (Stripe v1 은 status code 미명시, PayPal 은 "might fail" 모호 표현)
|
|
- response replay 의 정확한 메커니즘 (status+body cache vs 부분 재실행)
|
|
- 저장소 backend / lock 정책 (운영 핵심을 표준이 안 다룸)
|
|
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
|
- 2026-05-27 시점 latest draft (draft-08+ 가 있다면) 재확인 — draft 본문은 revision 마다 변할 수 있음
|
|
- ca-tmpl 200ms wait 동작이 `IETF-IDEMP-C4` 의 409 권장과 정합한지 (즉시 409 vs 짧은 wait 후 hit/409)
|
|
- 정식 RFC 승급 시 본 draft 의 어떤 부분이 변경되는지 monitoring
|
|
|
|
## ca-tmpl 함의 (내 프로젝트 해석)
|
|
|
|
> 본 섹션은 자료 직접 인용이 아닌 ca-tmpl 결정 컨텍스트 해석. wiki 추출 시 source-summary 로 옮겨야 함.
|
|
|
|
- **scope 자유**: ca-tmpl triple `(principal, key, useCaseName)` 은 draft 가 허용하는 "resource owner defines" (`IETF-IDEMP-C2`) 범위 안. Stripe v1 pair, ca-tmpl triple, body-hash 모두 표준 안에서 가능 — 표준 위반 아님.
|
|
- **422 fingerprint**: ca-tmpl 422 → draft 422 (`IETF-IDEMP-C3`) 와 일치.
|
|
- **409 in-flight**: ca-tmpl 200ms wait 는 draft 409 권장 (`IETF-IDEMP-C4`) 과 다른 선택. ca-tmpl 이 더 친절하지만 표준 동작은 아님. 면접 / 외부 인용 시 "표준 따름" 표현 금지, "표준 기반 + 운영 친화적 변형" 으로.
|
|
- **TTL 자유**: draft 가 시간을 정하지 않음 (`IETF-IDEMP-C5`) — ca-tmpl 24h, Stripe v1 24h, Stripe v2 30일, Toss 15일, PayPal 45일 모두 표준 안에서 가능.
|
|
|
|
## 메모 / Notes
|
|
|
|
- **draft status**: 정식 RFC 가 아니라 IETF httpapi WG 의 작업 중 초안 (draft-07, 2025-10, 2026-05-27 시점 status=expired). revision 마다 본문 변경 가능. 외부 인용 시 "IETF draft (work-in-progress)" 명시 필요. 절대 "IETF 표준" 으로 표현 금지. strength 를 `official-reference` 로 라벨 (정식 standard 가 아닌 IETF reference document).
|
|
- **2026-05-27 재검증**: WebFetch 완료. draft-07 본문 직접 fetch 하여 5개 quote 모두 verbatim 위치 확인. C1 의 "resource server" → "resource" 변화 발견 (2026-05-22 capture 의 표현은 더 이른 draft 본문이었거나 user 의 paraphrase 였을 가능성). 다른 4개는 verbatim 또는 더 긴 full sentence 형태로 MATCH.
|
|
- **단점 (해석)**: 표준이 너무 느슨해 구현체별 동작이 제각각 (Stripe·PayPal·Square 각각 다름). TTL / 저장 layer / lock 정책 등 운영 핵심을 표준이 안 다룸.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 raw:
|
|
- [[raw/official-docs/idempotency-stripe-api-ref]]
|
|
- [[raw/official-docs/idempotency-paypal-docs]]
|
|
- [[raw/company-tech-blogs/idempotency-toss-payments-techblog]]
|
|
- 인용하는 branch:
|
|
- [[raw/branch-notes/feature-rate-limit-idempotency-contract]]
|
|
- [[raw/branch-notes/feature-api-contract-baseline]]
|
|
- 인용하는 project:
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]] (§13, §18)
|
|
- 인용한 wiki 요약: (미작성)
|