멱등성이란 무엇인가
멱등성(Idempotency)이란 동일한 요청을 한 번 보내든 여러 번 보내든 결과가 똑같이 유지되는 성질을 말합니다. 쉽게 말해 ‘같은 버튼을 여러 번 눌러도 상태가 한 번 누른 것과 동일하게 유지되는 것’입니다. 엘리베이터 버튼을 떠올려보면 이해하기 쉽습니다. 이미 눌린 버튼을 다시 눌러도 엘리베이터가 추가로 호출되지 않고 동일한 상태가 유지되죠. API에서도 마찬가지로, 네트워크 오류나 타임아웃으로 클라이언트가 같은 요청을 재전송하더라도 서버의 최종 상태가 달라지지 않아야 멱등성이 보장된다고 말합니다.
HTTP 메서드와 멱등성 동작 원리
HTTP 스펙에서는 메서드별로 멱등성 여부가 정의되어 있습니다.
GET,PUT,DELETE는 멱등성을 가집니다. 예를 들어PUT /users/1로 이름을 ‘Kim’으로 수정하는 요청은 몇 번을 반복해도 결과는 동일하게 이름이 ‘Kim’인 상태입니다.POST는 일반적으로 멱등하지 않습니다.POST /orders로 주문 생성 요청을 두 번 보내면 주문이 두 개 생성될 수 있습니다.
여기서 주의할 점은 멱등성이 ‘응답이 항상 같다’는 뜻이 아니라 ‘서버의 상태 변화가 같다’는 뜻이라는 것입니다. DELETE 요청을 두 번 보내면 첫 번째는 200 OK, 두 번째는 404 Not Found를 반환할 수 있지만, 리소스가 삭제된 상태라는 결과 자체는 동일하므로 멱등하다고 볼 수 있습니다.
실무에서 멱등성이 중요한 이유
실무에서 멱등성이 중요한 가장 큰 이유는 네트워크 환경이 불안정하기 때문입니다. 클라이언트가 요청을 보냈는데 응답을 받기 전에 타임아웃이 발생하면, 서버가 처리를 완료했는지 알 수 없는 상황이 생깁니다. 이때 클라이언트는 재시도(retry)를 하게 되는데, 만약 API가 멱등하지 않다면 결제가 중복 처리되거나 주문이 중복 생성되는 심각한 문제가 발생할 수 있습니다.
그래서 결제나 주문 생성처럼 본질적으로 멱등하지 않은 POST 요청에도 멱등성을 부여하기 위해 ‘멱등성 키(Idempotency Key)’라는 기법을 사용합니다. 클라이언트가 요청마다 고유한 키를 헤더에 담아 보내면, 서버는 동일한 키로 들어온 요청을 이미 처리한 이력이 있는지 확인하고, 있다면 새로 처리하지 않고 이전 결과를 그대로 반환합니다. 실제로 결제 서비스인 Stripe API도 이 방식을 채택하고 있습니다.
결국 멱등성은 안정적인 분산 시스템과 신뢰할 수 있는 API를 설계하기 위한 핵심 원칙이며, 재시도 로직이 필수적인 현대 서비스 환경에서 반드시 고려해야 할 개념입니다.