- idempotency
- HTTP
- REST
멱등성이란 무엇인가요?
- 예상 시간
- 5분
멱등성(idempotency)은 한 번 실행한 뒤의 상태와 같은 요청을 여러 번 실행한 뒤의 상태가 같은 성질입니다. 여기서 비교하는 대상은 응답이 아니라 서버의 상태이고, 0회와 N회가 아니라 1회와 N회입니다.
HTTP 메서드 중 GET, HEAD, PUT, DELETE는 멱등하고, POST는 멱등하지 않습니다. 네트워크 오류로 재시도할 때 멱등한 요청은 안전하게 다시 보낼 수 있습니다.
멱등이라는 단어는 수학에서 왔습니다. f(f(x)) = f(x)를 만족하는 연산을 멱등이라 합니다. 절댓값 함수 abs(abs(x)) = abs(x)가 예입니다.
'같은 결과'라고만 외우면 두 군데에서 막힙니다. 첫째, 같아야 하는 것은 응답이 아니라 상태입니다. DELETE /users/1은 첫 요청에 200을, 두 번째 요청에 404를 돌려주지만 서버 상태는 '1번 사용자 없음'으로 동일하므로 멱등합니다. 응답을 기준으로 재면 DELETE가 멱등이 아니라는 잘못된 결론이 나옵니다.
둘째, 그 요청만 반복했을 때를 말합니다. GET /users/1을 두 번 보내는 사이에 다른 사람이 값을 수정해서 응답이 달라졌다면 그건 멱등성 위반이 아닙니다. 내 요청이 만든 차이가 아니기 때문입니다.
네트워크는 불안정합니다. 요청을 보냈는데 응답이 안 오면 서버가 처리했는지 모릅니다. 멱등한 요청이라면 그냥 다시 보내면 됩니다. 멱등하지 않으면 "이미 처리됐을 수 있는데 또 보내도 되나?"를 신경 써야 합니다. 분산 시스템에서 at-least-once delivery(최소 한 번 전달)를 쓸 때 멱등성이 필수입니다.
꼬리질문
답변 뒤에 이어질 수 있는 질문들을 하나씩 열어볼 수 있어요.
HTTP 메서드별 멱등성은?
GET, HEAD, PUT, DELETE는 멱등합니다. POST와 PATCH는 멱등하지 않습니다.
| 메서드 | 멱등 | 이유 |
|---|---|---|
| GET | O | 조회만, 상태 변경 없음 |
| HEAD | O | GET과 같지만 body 없음 |
| PUT | O | 같은 데이터로 덮어씌우므로 결과 동일 |
| DELETE | O | 이미 없는 리소스를 또 삭제해도 "없음" 상태 동일 |
| POST | X | 매번 새 리소스 생성 가능 |
| PATCH | X | 상대적 변경이면 누적됨 |
GET과 HEAD는 상태를 아예 바꾸지 않아서 멱등하고, PUT과 DELETE는 상태를 바꾸지만 두 번째 요청부터 더 바뀌지 않아서 멱등합니다. 멱등의 조건은 후자이고, 전자는 그보다 강한 조건입니다.
DELETE가 멱등한 이유는 "없는 상태"가 목적이기 때문입니다. 이미 삭제된 리소스에 DELETE를 다시 보내면 404가 오지만, 서버 상태 자체는 "해당 리소스 없음"으로 동일합니다.
PUT이 멱등한 이유는 리소스 전체를 보내서 덮어쓰기 때문입니다. PUT /users/1 { name: "홍길동" }을 열 번 보내도 결과는 항상 name이 "홍길동"입니다.
POST는 /orders에 주문 생성 요청을 보낼 때, 같은 요청을 두 번 보내면 주문이 두 개 생깁니다. 멱등하지 않습니다.
safe와 idempotent는 어떻게 다른가요?
safe는 상태를 아예 바꾸지 않는 성질이고, idempotent는 첫 실행에서 상태를 바꿔도 그 뒤로 더 바뀌지 않는 성질입니다. safe한 메서드는 자동으로 멱등하지만 그 반대는 성립하지 않습니다.
| safe | idempotent | 메서드 | |
|---|---|---|---|
| 상태를 안 바꿈 | O | O | GET, HEAD, OPTIONS |
| 첫 실행만 바꿈 | X | O | PUT, DELETE |
| 매번 바꿈 | X | X | POST |
네 번째 칸인 'safe인데 멱등하지 않음'은 존재할 수 없습니다. 상태를 바꾸지 않으면 몇 번을 실행해도 상태가 같기 때문입니다.
두 성질이 보장하는 것도 다릅니다. 멱등성은 재시도 안전성을 보장하고, safe는 요청을 마음대로 미리 보내도 되는 자유를 보장합니다. 브라우저의 프리페치, 프록시 캐시, 검색 엔진 크롤러는 GET이 safe하다는 전제로 사용자가 누르지도 않은 링크를 미리 요청합니다.
그래서 삭제나 상태 변경을 GET 링크로 만들면 사고가 납니다. 프리페치나 크롤링만으로 데이터가 지워지는 사례가 알려져 있습니다. DELETE /users/1은 멱등하지만 safe하지 않으므로, 이 구분을 알아야 어떤 동작을 GET에 얹으면 안 되는지 판단할 수 있습니다.
PUT과 PATCH의 멱등성 차이는?
PUT은 리소스 전체를 교체하므로 멱등합니다. PATCH는 일부만 수정하는데, 수정 방식에 따라 멱등할 수도 아닐 수도 있습니다.
PATCH가 멱등하지 않은 케이스는 상대적 변경입니다.
PATCH /users/1
{ "increment_age": 1 }이 요청을 두 번 보내면 나이가 2 올라갑니다. 반면
PATCH /users/1
{ "age": 30 }이 요청은 몇 번을 보내도 나이가 30으로 고정됩니다. 멱등합니다.
REST API 설계에서 PATCH를 멱등하게 설계할지는 선택입니다. 다만 클라이언트가 재시도할 때를 고려하면 멱등하게 만드는 것이 안전합니다.
재시도 로직에서 멱등성이 왜 중요한가요?
네트워크 오류로 요청의 성공 여부를 알 수 없을 때 안전하게 재시도하려면 멱등성이 필요합니다. 멱등하지 않은 요청을 재시도하면 중복 처리가 생길 수 있습니다.
결제 API가 대표적입니다. 결제 요청을 보냈는데 응답이 timeout됐을 때, 결제가 됐는지 모르는 상태에서 그냥 재시도하면 이중 결제가 생깁니다.
해결 방법은 idempotency key입니다. 클라이언트가 요청마다 고유한 키를 헤더에 포함해 보내면, 서버가 같은 키로 이미 처리한 요청인지 확인해 중복을 막습니다.
POST /payments
Idempotency-Key: a3b8f2e-4c91-...
{ "amount": 10000 }같은 Idempotency-Key로 재시도하면 서버가 이전 응답을 그대로 돌려줍니다. Stripe, Toss 같은 결제 서비스가 이 패턴을 씁니다.
한 줄 정리
멱등성은 요청을 한 번 보낸 뒤와 여러 번 보낸 뒤의 서버 상태가 같은 성질로, 재시도 안전성의 핵심 조건입니다.