fix: 하네스 제거 및 keycloak 문서 보강
This commit is contained in:
DongHyeonka
@@ -1 +0,0 @@
|
||||
../../vault/20-evidence/official-docs/idempotency-square-api.md
|
||||
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: Square API — Idempotency (Common API patterns)
|
||||
source_type: official-doc
|
||||
url: https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency
|
||||
archive_url:
|
||||
status: raw
|
||||
confidence: high
|
||||
tags: [ca-idempotency, square, payment-domain, body-mismatch-error, official-doc]
|
||||
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
|
||||
---
|
||||
|
||||
# Square API — Idempotency
|
||||
|
||||
> Layer: `raw/official-docs/` — Square Developer 공식 "Common API patterns" 페이지 발췌. ca-tmpl Topic 5 의 "body fingerprint mismatch → 명시적 error" 정책의 동일 사상 사례.
|
||||
|
||||
## Parent / 활용 branch (필수)
|
||||
|
||||
| Branch | 이 자료가 정당화하는 결정 |
|
||||
|---|---|
|
||||
| [[raw/branch-notes/feature-rate-limit-idempotency-contract]] | "다른 body 면 error" 정책 (ca-tmpl 422) 의 결제 도메인 공식 사례 — Stripe 와 함께 body fingerprint mismatch 처리의 표준 패턴 근거 |
|
||||
| [[raw/branch-notes/feature-api-contract-baseline]] | API contract baseline 에서 header vs body 필드 위치 선택의 trade-off (Square 는 body, Stripe/IETF draft 는 header) |
|
||||
|
||||
## 컨텍스트 / 왜 저장했는지
|
||||
|
||||
Square는 `idempotency_key`를 **header가 아닌 body 필드**로 받는 드문 케이스. fingerprint 처리도 "다른 body면 error"로 명시. ca-tmpl의 422 정책과 가장 가까운 도메인 사례.
|
||||
|
||||
## 출처 / Source
|
||||
|
||||
- 원본 URL: https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency
|
||||
- 아카이브 URL: (미수집)
|
||||
- 저자 / 조직: Square Developer (Block, Inc.)
|
||||
- 발행일: rolling docs
|
||||
- 마지막 확인일: 2026-05-27
|
||||
- 보조: Square blog "Understanding the Essentials: Idempotency"
|
||||
- 보조: Square API reference (`POST /v2/payments`, `POST /v2/payments/cancel`)
|
||||
|
||||
## 핵심 인용 / Key quotes (verbatim)
|
||||
|
||||
> [§What is idempotency?] "Square supports idempotency by allowing API operations to provide an idempotency key (a unique string)..."
|
||||
|
||||
> [§What is idempotency?] "If you use the same idempotency key but change the `CreatePayment` request (for example, specify a different payment amount), you get an error indicating that you used the idempotency key previously."
|
||||
|
||||
> [§What is idempotency?] "...the endpoint returns the response as the first successful `CreatePayment` response."
|
||||
|
||||
> [§What is idempotency?] "Idempotency keys can be anything, but they need to be unique."
|
||||
|
||||
## Claims Extracted / 추출된 주장
|
||||
|
||||
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
||||
|---|---|---|---|---|---|
|
||||
| IDMP-SQ-C1 | Square 의 idempotency 는 API operation 이 unique string 인 idempotency key 를 제공하는 방식으로 지원됨 | [§What is idempotency?] "Square supports idempotency by allowing API operations to provide an idempotency key (a unique string)..." | `official-vendor-doc` | Square API operations 중 idempotency_key 를 지원하는 endpoint | 모든 Square endpoint 가 idempotency_key 를 지원한다는 뜻은 아님 — 명시된 endpoint (CreatePayment 등) 한정 |
|
||||
| IDMP-SQ-C2 | 같은 idempotency key 로 다른 request (예: payment amount 변경) 를 보내면 "이미 사용한 키" 라는 error 응답 — body fingerprint mismatch 시 명시적 거부 | [§What is idempotency?] "If you use the same idempotency key but change the `CreatePayment` request (for example, specify a different payment amount), you get an error indicating that you used the idempotency key previously." | `official-vendor-doc` | CreatePayment 및 유사 endpoint | 정확한 HTTP status code (409 / 422 / 400) 는 본 인용에 명시되지 않음 — Square API reference 별도 확인 필요. "Note that this behavior might vary depending on the API." (Square 본문 caveat) |
|
||||
| IDMP-SQ-C3 | 완료된 같은 idempotency key 의 replay → 첫 성공 응답을 그대로 반환 | [§What is idempotency?] "...the endpoint returns the response as the first successful `CreatePayment` response." | `official-vendor-doc` | 동일 key + 동일 body 의 retry | TTL (replay 가능 기간) 은 본 인용에 명시되지 않음 — Square 문서의 알려진 갭 |
|
||||
| IDMP-SQ-C4 | idempotency key 의 값은 임의의 string 이지만 unique 해야 함 | [§What is idempotency?] "Idempotency keys can be anything, but they need to be unique." | `official-vendor-doc` | 클라이언트의 key 생성 정책 | "unique" 의 scope (글로벌 / merchant 단위 / endpoint 단위) 가 무엇인지 본 인용에서는 불명확 — 별도 endpoint 문서 확인 필요 |
|
||||
|
||||
## Usage Boundaries / 적용 경계
|
||||
|
||||
- **이 자료가 직접 증명하는 것**:
|
||||
- `IDMP-SQ-C1`: Square 의 idempotency 지원 방식 (client-supplied unique key)
|
||||
- `IDMP-SQ-C2`: body fingerprint mismatch 시 명시적 error (ca-tmpl 422 정책의 동일 사상)
|
||||
- `IDMP-SQ-C3`: 완료된 키의 first response replay
|
||||
- `IDMP-SQ-C4`: key uniqueness 요구
|
||||
- **이 자료가 증명하지 않는 것**:
|
||||
- idempotency key 의 정확한 위치 (header vs body 필드) — 본 발췌에는 명시 없음, Square API reference 의 endpoint 별 schema 에서 `idempotency_key` 가 request body 필드로 정의되어 있음을 별도 확인 필요
|
||||
- TTL / 보존 기간 — Square 문서의 알려진 갭
|
||||
- in-flight (동일 key 의 동시 호출) 처리 방식 — 본 인용에 명시 없음
|
||||
- mismatch error 의 정확한 HTTP status code
|
||||
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
||||
- ca-tmpl 이 422 를 채택할 때 Square 의 error code 를 1:1 대응시킬 수 있는지 (Square 의 정확한 code 확인 후 본문 매핑)
|
||||
- header vs body 필드 선택의 trade-off (미들웨어 dedup 가능성 vs API contract 단순성)
|
||||
|
||||
## 메모 / Notes (내 프로젝트 해석)
|
||||
|
||||
> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.
|
||||
|
||||
- **key scope (어떤 dimension으로):** body 필드로 받고 endpoint별로 처리 → `(merchant_account, endpoint, idempotency_key)`. ca-tmpl triple과 거의 동일 구조.
|
||||
- **TTL:** 문서에 명시 안됨 (Square의 단점 중 하나로 자주 지적됨).
|
||||
- **저장소:** 미공개.
|
||||
- **duplicate 처리:**
|
||||
- 완료된 동일 key + **동일 request** → first response 반환.
|
||||
- 완료된 동일 key + **다른 request** → error.
|
||||
- **fingerprint (same key, different body):** **명시적으로 error 반환**. ca-tmpl 422 정책과 같은 사상.
|
||||
- **in-flight:** 문서 명시 없음.
|
||||
- **장점:**
|
||||
- body fingerprint 정책이 명시적이라 클라이언트 버그 조기 발견.
|
||||
- `cancel-payment-by-idempotency-key`처럼 키 자체를 resource handle로 쓰는 API 디자인 가능 (Stripe·PayPal엔 없음).
|
||||
- **단점:**
|
||||
- body 필드 방식 → 헤더 표준(IETF draft, Stripe, PayPal)과 호환 안 됨. 미들웨어 레벨에서 dedup 어려움.
|
||||
- TTL 미공개 → 클라이언트가 retry 윈도우를 못 가늠.
|
||||
- in-flight 동작 미정의.
|
||||
- **ca-tmpl과의 차이:**
|
||||
- ca-tmpl은 header 기반 (IETF 표준 준수), Square는 body 필드 → ca-tmpl이 더 표준에 가까움.
|
||||
- fingerprint mismatch error: 두 시스템 모두 동일 사상. ca-tmpl이 422라는 status code까지 명시한 게 한 단계 더 엄격.
|
||||
- scope: 사실상 동급 (양쪽 다 account + endpoint + key).
|
||||
- in-flight: Square 미정의 vs ca-tmpl 200ms wait → ca-tmpl이 명시적·예측 가능.
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 같은 주제 다른 official-doc:
|
||||
- [[raw/official-docs/idempotency-aws-lambda-powertools]] — server-derived key 모델
|
||||
- [[raw/official-docs/idempotency-no-api-level-github-rest]] — server dedup 부재 모델
|
||||
- canonical contract 섹션:
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] §13. API Contract Surface (Idempotency-Key)
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] §18. Control Plane Contract (Rate Limit/Idempotency)
|
||||
- 대안 그룹: **Topic 5 — Idempotency** (대안 5종 + 보조 1종: triple scope / Stripe pair / URL-based / content-hash / no-dedup / + DB vs Redis 저장소)
|
||||
- 본 source의 위치: **대안 4: Square endpoint-scoped**
|
||||
Reference in New Issue
Block a user