멱등성(Idempotency)이란 무엇이며 API 설계에 왜 중요한가

멱등성(Idempotency)이란 동일한 요청을 한 번 보내든 여러 번 보내든 서버의 최종 상태가 동일하게 유지되는 성질을 말합니다. 예를 들어 "특정 값을 100으로 설정하라"는 요청은 몇 번을 반복해도 결과가 항상 100이므로 멱등하지만, "현재 값에 100을 더하라"는 요청은 반복할 때마다 값이 계속 증가하므로 멱등하지 않습니다. HTTP 메서드 중에서는 GET, PUT, DELETE가 원칙적으로 멱등하도록 설계되어 있습니다. GET은 조회만 하므로 당연히 상태를 바꾸지 않고, PUT은 리소스를 특정 값으로 통째로 덮어쓰기 때문에 여러 번 호출해도 같은 결과가 됩니다. 반면 POST는 일반적으로 새 리소스를 생성하는 데 쓰이기 때문에, 같은 요청을 두 번 보내면 리소스가 두 개 생기는 비멱등적인 동작이 기본값입니다. 이 개념이 특히 중요해지는 상황은 네트워크가 불안정한 환경입니다. 클라이언트가 결제 요청을 보냈는데 응답을 받기 전에 타임아웃이 발생하면, 클라이언트 입장에서는 요청이 성공했는지 실패했는지 알 수 없어 재시도를 하게 됩니다. 이때 서버가 결제 처리 API를 멱등하게 설계해두지 않았다면, 재시도로 인해 같은 결제가 중복으로 청구되는 심각한 문제가 발생할 수 있습니다. 실무에서는 이런 문제를 막기 위해 클라이언트가 요청마다 고유한 멱등키(Idempotency Key)를 함께 보내는 방식을 자주 사용합니다. 서버는 동일한 멱등키로 들어온 요청을 이미 처리한 적이 있는지 확인하고, 이미 처리된 요청이라면 실제 로직을 다시 실행하지 않고 저장해둔 이전 결과를 그대로 반환합니다. 이렇게 하면 클라이언트가 안심하고 재시도를 보낼 수 있는 API가 만들어집니다.