멱등성(Idempotency)

✅ 멱등성(Idempotency)과 API 설계의 원칙

---

1. 멱등성이 뭐길래?

“결제 버튼을 두 번 눌러도 괜찮을까?”

모바일 앱에서 결제 버튼을 눌렀는데 아무 반응이 없다. 불안해진 사용자는 버튼을 한 번 더 누른다. 몇 초 뒤, 주문 내역에 동일한 결제가 두 번 잡혀 있다. 당황한 사용자는 고객센터에 전화를 건다. 서버 개발자는 로그를 뒤지고, 팀장은 긴급 회의를 소집한다.

이 사소한 시작은 곧 시스템의 신뢰성 문제로 번지고, 고객의 불만은 브랜드 이미지까지 흔든다. 이 모든 사태를 막는 단 하나의 기술적 원칙이 바로 **멱등성(Idempotency)**이다.

멱등성이란 같은 요청을 여러 번 보내도 결과는 한 번만 발생하는 성질이다. 처음 들으면 단순해 보이지만, API 설계에서 이 원칙을 지키는 일은 매우 중요하고도 까다로운 과제이다.

---

2. 멱등성이 중요한 이유

멱등성이 없다면, 사용자의 실수, 네트워크 지연, 재요청 등으로 인해 서버가 같은 요청을 반복해서 처리하게 된다. 반대로 멱등성이 있다면, 서버는 이전 요청을 기억하고 의도치 않은 중복 처리를 방지한다.

📦 예시: 택배 상자 이야기

• 사용자가 “택배 상자를 없애 주세요”라는 요청(DELETE)을 보냈다.
• 택배 회사는 그 상자를 수거했다.
• 그런데, 네트워크 문제로 사용자는 같은 요청을 한 번 더 보냈다.
• 멱등성이 있다면, 택배 회사는 “이미 가져갔어요”라고 응답할 수 있다.
• 멱등성이 없다면, 택배 기사가 없는 상자를 또 수거하려고 달려간다. 혼란이다.

HTTP 메서드 중 GET, PUT, DELETE는 멱등성을 기본으로 가진다. 반면 POST는 기본적으로 멱등성을 보장하지 않으므로, 특별한 설계가 필요하다.

---

3. API 설계에서 멱등성을 구현하는 방법

(1) 메서드를 제대로 고른다

• GET: 조회만 하므로 언제든 재요청 가능
• PUT: 전체를 “덮어쓰기”하므로, 같은 요청 = 같은 상태
• DELETE: 이미 없애버린 건 다시 없애도 변화 없음
• POST: 새 리소스 생성이기 때문에 요청마다 결과가 다를 수 있음

(2) POST에서도 멱등성을 만들 수 있다

비유: 우체통에 편지 넣기

• 누군가 같은 편지를 우체통에 두 번 넣었다.
• 이를 방지하려면 편지 봉투에 **고유 번호(Idempotency Key)**를 적고,
• 우체국이 그 번호를 보고 “아, 이건 이미 받은 거군요.”라고 인식하면 중복을 피할 수 있다.

API에서도 이와 동일하게 X-Idempotency-Key를 활용할 수 있다. 예:

POST /payments
X-Idempotency-Key: 8a1b-77d0-xyz

{
  "amount": 15000,
  "user_id": 123
}

서버는 이 키를 확인하고, 이미 처리된 요청이면 이전 결과를 그대로 반환한다. 이렇게 하면 두 번 버튼을 눌러도 결제는 한 번만 이뤄진다.

---

4. 멱등성이 없을 때 실제로 벌어지는 일들

🧨 사례: 항공권 중복 결제

실제 한 항공사에서는 모바일 앱의 버튼 클릭 시 서버와의 응답이 늦어지는 일이 자주 발생했다. 고객들이 불안해서 같은 예약 요청을 반복했고, 결과적으로 한 좌석에 중복 결제가 수십 건 발생했다. 수작업으로 정리하는 데 하루가 넘게 걸렸고, 고객 불만은 SNS로 확산됐다.

이 사건 이후, 이 항공사는 모든 주요 POST 요청에 대해 Idempotency-Key를 의무화하고, 캐싱 전략을 도입했다.

---

5. 결론: 다시 눌러도 괜찮은 시스템을 만든다는 것

멱등성은 단지 “한 번만 처리되게 하자”는 기술적인 목표를 넘어서서, 사용자 경험과 신뢰성을 지키는 안전장치이다.

왜 중요한가?

• 사용자는 시스템이 빠르게 반응하지 않으면 다시 요청한다.
• 개발자는 서버가 그 요청을 똑같이 처리하지 않도록 만들어야 한다.
• 이를 위해선 멱등성 설계가 필수적이다.

📌 기억할 것

멱등성은 “요청을 기억하는 것”이 아니라, “결과를 같게 만드는 것”이다.

---

📎 정리

항목	멱등성 여부	설명
GET /users/1	✅ 있음	같은 유저 정보 조회
DELETE /users/1	✅ 있음	이미 지운 유저는 다시 지워도 결과 동일
POST /orders	❌ 없음 (주의!)	멱등성 키 없으면 중복 주문 가능
POST /orders + X-Idempotency-Key	✅ 보완됨	같은 주문임을 인식하고 중복 생성 방지

---

REFERENCE

멱등성(Idempotency)의 이해와 API 설계에서의 중요성