REST API 설계의 핵심, 멱등성(Idempotency) 완벽 이해하기

멱등성이란 무엇인가요?

멱등성(Idempotency)은 컴퓨터 과학과 네트워크 프로그래밍에서 아주 중요한 개념입니다. 쉽게 설명하면, 어떤 작업을 여러 번 반복해서 실행해도 결과가 최초 실행과 똑같이 유지되는 성질을 말합니다. 예를 들어, 전구 스위치를 ‘켜기’ 상태로 여러 번 눌러도 전구가 켜져 있는 상태로 변하지 않는 것처럼요. 이 개념은 특히 REST API 설계에서 핵심적인 역할을 합니다.

왜냐하면 네트워크 요청이 전송 중에 끊기거나 재전송되는 상황이 자주 발생하거든요. 이럴 때 서버가 멱등성을 보장하면 동일한 요청이 여러 번 들어와도 데이터가 중복 생성되거나 상태가 이상하게 변하지 않아서, 예기치 않은 버그와 오류를 예방할 수 있습니다.

REST API에서 멱등성의 중요성

REST API를 설계할 때, HTTP 메서드별 멱등성 특성을 아는 게 정말 중요합니다. 기본적으로 GET, PUT, DELETE 메서드는 멱등성을 가진다고 정의되어 있습니다. 반면, POST 메서드는 멱등하지 않은 경우가 많아요.

GET은 단순히 데이터를 조회하기 때문에 언제 여러 번 호출해도 서버의 상태를 바꾸지 않습니다.

PUT은 자원의 상태를 특정 값으로 바꾸는 작업입니다. 같은 데이터를 여러 번 PUT해도 결국 최종 상태는 같으므로 멱등합니다.

DELETE는 자원을 제거하는 명령인데, 여러 번 DELETE를 요청해도 자원이 없으면 더 이상 삭제할 대상이 없을 뿐이니 멱등성을 지키죠.

POST는 일반적으로 새로운 자원을 생성하는 용도라서 매번 호출 시마다 결과가 달라질 수 있어 멱등성을 갖지 않는 경우가 많습니다.

이 차이를 이해하지 못하면 API 사용자가 의도치 않은 중복 작업이나 시스템 장애를 경험할 수 있어요. 그래서 API를 설계할 때 이 부분을 명확히 하고, 가능하면 POST 요청도 멱등성이 되도록 설계하는 것이 좋습니다.

멱등성 보장을 위한 REST API 설계 팁

그럼 구체적으로 어떻게 하면 REST API에서 멱등성을 잘 보장할 수 있을까요? 몇 가지 전략과 팁을 소개해드릴게요.

PUT 메서드 활용하기
리소스의 전체 상태를 변경할 때는 PUT을 사용하세요. 같은 PUT 요청을 여러 번 보내도 항상 같은 상태가 유지되니 멱등성을 자연스럽게 확보할 수 있습니다.

POST 요청에 멱등 키(Idempotency Key) 도입하기
POST 요청은 일반적으로 멱등하지 않지만, 요청 헤더에 유니크한 멱등 키를 추가해서 서버가 이를 기준으로 이전 요청의 처리가 있었는지 판단하게 할 수 있습니다. 이렇게 하면 중복된 생성 요청을 막을 수 있죠.

상태 변경 작업 구분 명확히 하기
예를 들어, 결제 API 같은 경우 결제 요청이 여러 번 들어왔을 때 중복 결제 되는 걸 막기 위해 멱등 키나 트랜잭션 ID를 반드시 사용해야 합니다. 주요 상태 변경 작업일수록 멱등성 고려는 필수입니다.

오류 복구 로직과 함께 설계하기
클라이언트가 요청을 재전송할 때 서버가 이전 요청을 어떻게 처리했는지 기억하는 캐시나 DB 상태가 있어야 합니다. 이를 기반으로 중복 실행을 차단하거나 정상 응답을 재전송할 수 있어야 하죠.

API 문서에 멱등성 명확히 명시하기
개발자들이 API를 사용하면서 혼란이 없도록 각 엔드포인트가 멱등성을 가지는지, 멱등 키 사용 여부 등을 문서에 분명히 표기하세요. 설계 철학이 분명해야 API 확장과 유지보수도 수월해집니다.

멱등성의 실제 사례: 머니 트랜잭션과 주문 처리

예를 들어 간단히 온라인 쇼핑몰의 주문 처리를 생각해볼까요? 사용자가 ‘결제 요청’ 버튼을 누르면 POST 요청이 서버로 가고, 결제가 승인되어야 주문이 완료됩니다. 하지만 네트워크 오류로 인해 같은 요청이 몇 차례 중복 전송된다면 어떻게 될까요? 결제가 두 번 이상 이루어질 수도 있겠죠?

이때 멱등 키를 도입하면 서버는 첫 결제 요청 이후 같은 키로 들어온 요청을 무시하거나 이전 결과를 반환하게 돼 중복 결제가 발생하지 않아요. 이런 멱등성 보장은 사용자 경험을 크게 개선하고, 기업의 금전적 손실도 예방합니다.

또 다른 예는 주문 취소 API에서 DELETE를 사용하면 됩니다. 여러 번 취소 요청이 들어와도 주문 상태는 ‘취소됨’으로 한 번만 변하고, 이후 요청에는 별다른 변화가 없으니 멱등성이 보장됩니다.

멱등성을 잘 활용해야 하는 이유

결국 멱등성은 API 신뢰성과 안정성의 근간입니다. 한 번의 요청이 여러 번 처리되더라도 시스템이 일관된 상태를 유지하게 하니까요. 멱등성을 고려하지 않은 API는 데이터 중복 오류, 부정확한 상태 표현, 사용자 혼란, 심지어 경제적 피해까지 유발할 수 있습니다.

또한 대규모 서비스에서 네트워크 오류는 빈번하기에, 멱등성을 무시하면 장애 발생률이 급격히 상승합니다. 그래서 API 설계 시에 멱등성을 검토하는 것은 개발자의 기본 덕목입니다.

맺음말

멱등성은 복잡해 보일 수 있지만, 쉽게 말해 ‘몇 번을 해도 결과는 동일하다’는 뜻입니다. REST API를 설계하실 때는 이 개념을 철저히 적용해보세요. 특히 POST 요청에도 멱등성을 부여하는 꼼꼼함이 중요합니다. 이게 바로 견고하고 신뢰받는 API로 가는 첫걸음이니까요. 멱등성을 이해하고 실천하면, 더 적은 문제와 더 많은 만족을 선사하는 API를 만들어낼 수 있습니다. 꼭 기억해 주세요!