멱등성

어떤 작업을 반복해도 한 번 했을 때와 서버에 같은 효과를 낸다면 그 작업은 멱등(idempotent)합니다. 네트워크는 실패하기 때문에 이 성질이 중요합니다. 타임아웃이 난 클라이언트는 요청이 도착했는지 알 수 없고, 재시도는 요청이 멱등할 때만 안전합니다. 멱등성(Idempotency)은 매번 같은 응답을 받는 것이 아니라 서버 상태에 관한 것입니다.

멱등한 HTTP 메서드

메서드	멱등	안전(부수 효과 없음)
GET, HEAD, OPTIONS	예	예
PUT	예	아니요
DELETE	예	아니요
POST	아니요	아니요
PATCH	보장되지 않음	아니요

DELETE /orders/42를 두 번 보내면 처음에는 204, 다음에는 404가 반환될 수 있습니다. 응답은 다르지만 상태는 같습니다. 주문은 사라졌습니다. 이것도 여전히 멱등입니다.

PUT과 PATCH의 차이

PUT은 보낸 본문으로 리소스 전체를 교체합니다. {"name": "Ada", "plan": "pro"}로 PUT /users/7을 세 번 보내도 매번 같은 사용자가 남으므로 멱등합니다.

PATCH는 변경을 적용하며, 멱등한지는 변경 내용에 달려 있습니다. {"plan": "pro"}는 값을 설정하므로 실질적으로 멱등합니다. 하지만 “loginCount를 1 증가”나 배열에 대한 JSON Patch add 같은 작업은 매번 다른 결과를 내므로, 메서드로서의 PATCH는 멱등성이 보장되지 않습니다.

POST를 안전하게 재시도하기

결제와 주문 API는 흔히 멱등키(idempotency key)를 받습니다. 클라이언트가 고유한 값을 생성해 Idempotency-Key 같은 헤더로 보냅니다. 서버는 그 키로 들어온 첫 요청의 결과를 저장하고, 반복 요청에는 두 번째 주문을 만드는 대신 같은 결과를 반환합니다.

POST /payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: 6f1c2a9e-3b7d-4f0a-9c2e-1d5b8a7e4f60

{"amount": 4999, "currency": "EUR"}

테스트 방법

• 같은 PUT이나 DELETE를 두 번 보내고, 상태 코드만이 아니라 리소스 상태를 어설션하세요.
• 같은 멱등키로 같은 POST를 두 번 보내세요. 리소스는 하나, 응답 본문은 같아야 합니다.
• 같은 키를 다른 본문과 함께 재사용하세요. 잘 설계된 API는 이전 결과를 조용히 반환하지 않고 이를 거부합니다.
• 중복 요청을 동시에 보내세요. 멱등성 처리는 주로 경쟁 조건(race condition)에서 깨집니다.