REST API 리소스 업데이트 설계 시 PUT과 PATCH 차이 분석과 상황별 선택 기준
REST API에서 데이터 수정 엔드포인트를 설계할 때 혼동하기 쉬운 PUT과 PATCH 메서드의 기술적 차이와 멱등성 원리를 분석하고 실무 상황에 맞는 선택 기준을 정리합니다.
리소스 수정 API 설계 시 PUT과 PATCH 선택이 필요한 상황
웹 서비스를 개발하거나 외부 연동용 RESTful API를 설계할 때 데이터 수정 작업은 가장 빈번하게 마주치는 기능 중 하나입니다. 클라이언트가 특정 사용자 프로필, 게시물 내용, 혹은 주문 상태를 변경해야 하는 화면을 구현할 때 백엔드 개발자는 보통 HTTP 명세에 정의된 수정 메서드를 배치하게 됩니다. 이때 리소스 전체를 갈아 끼우는 방식과 일부 속성값만 변경하는 방식 사이에서 어떤 HTTP 메서드를 채택해야 할지 혼선이 생기기 쉽습니다.
초급 개발 환경에서는 GET과 POST만으로 모든 CRUD를 해결하거나 단순히 데이터를 바꾼다는 이유로 PUT만 일괄 적용하는 경우가 적지 않습니다. 하지만 API를 공개하거나 모바일 앱, 다양한 외부 프론트엔드와 안정적으로 통신하려면 HTTP 표준 규약에 맞는 메서드 분리가 필수적입니다. 페이로드의 누락이 기존 데이터를 삭제하는 부작용을 낳거나 네트워크 재시도 과정에서 데이터 일관성이 깨지는 문제를 사전에 예방하기 위해 두 메서드의 성격을 명확히 구분해야 합니다.
멱등성과 교체 범위로 살펴보는 핵심 비교 기준
PUT과 PATCH를 구별하는 가장 핵심적인 기술 기준은 RFC 표준에 정의된 '멱등성(Idempotency)'과 '리소스 반영 범위'입니다. RFC 9110(구 RFC 7231)에 따르면 PUT 메서드는 멱등성을 지닙니다. 즉 동일한 페이로드를 담아 요청을 한 번 보내든 열 번 연속으로 전송하든 서버의 최종 리소스 상태는 항상 같아야 합니다. 이는 PUT이 리소스의 특정 필드만 고치는 것이 아니라 URI가 가리키는 대상 리소스 전체를 요청 본문의 내용으로 '완전히 대체(Replace)'하는 의미를 갖기 때문입니다.
반면 RFC 5789에 명시된 PATCH 메서드는 기존 리소스에 대한 '부분 수정(Partial Update)'을 목적으로 고안되었습니다. 클라이언트는 변경하고 싶은 일부 필드와 그 값만을 전송하며 서버는 해당 지침에 따라 기존 리소스의 일부분만 갱신합니다. RFC 명세상 PATCH는 반드시 멱등성을 보장해야 하는 메서드가 아닙니다. 예를 들어 리소스의 특정 배열 필드에 항목을 덧붙이거나(append) 카운터 값을 1씩 증가시키는 형태의 연산이 포함된 PATCH 요청을 여러 번 보내면 매번 결과가 달라질 수 있습니다.
전체 교체와 부분 수정의 상황별 동작 차이 분석
동작 메커니즘을 구체적으로 비교해 보면 페이로드에 누락된 필드를 서버가 어떻게 다루는가에서 결정적인 차이가 나타납니다. PUT 요청의 경우 클라이언트가 본문에 포함하지 않은 기존 필드는 명세상 기본값으로 초기화되거나 null로 덮어씌워져야 합니다. 가령 이름, 이메일, 주소를 가진 사용자 리소스에 대해 이름만 담긴 페이로드로 PUT 요청을 전송한다면 이메일과 주소 데이터는 삭제되거나 초기화되는 것이 표준 동작 방식입니다.
반대로 PATCH 요청에서는 페이로드에 누락된 필드가 기존 상태를 그대로 유지합니다. 이름 필드만 전송했다면 기존에 저장되어 있던 이메일과 주소 필드는 아무런 영향을 받지 않고 오직 이름 데이터만 새 값으로 변경됩니다. 이 차이는 클라이언트의 네트워크 전송량에도 직접적인 영향을 미칩니다. 대용량 리소스에서 단순 스위치 토글이나 짧은 텍스트 한 줄만 바꿀 때 전체 데이터를 왕복시키는 PUT 방식은 불필요한 대역폭 낭비와 동시성 충돌을 유발할 수 있습니다.
실무 예시로 확인하는 회원 정보 수정 페이로드와 메서드 선택
가상의 회원 프로필 리소스를 관리하는 상황을 예로 들어보겠습니다. 식별자 101번 회원의 현재 상태가 이름은 홍길동, 연락처는 010-0000-0000, 닉네임은 길동이라고 가정합니다. 관리자 콘솔에서 회원의 전체 정보를 일람 양식으로 불러온 뒤 모든 필드를 한 번에 검증하여 저장하는 관리 페이지라면 PUT /api/v1/users/101 엔드포인트를 적용할 수 있습니다. 이때 요청 본문에는 식별자를 제외한 이름, 연락처, 닉네임 전체 데이터가 누락 없이 JSON 객체로 전달되어야 합니다.
반면 모바일 앱의 마이페이지에서 사용자가 닉네임 옆의 수정 버튼을 눌러 닉네임만 '행복한길동'으로 변경하는 UI라면 PATCH /api/v1/users/101을 호출하는 것이 바람직합니다. 요청 페이로드로 {"nickname": "행복한길동"} 하나만 전송하더라도 서버는 연락처와 본명을 안전하게 보존합니다. 만약 이 상황에 PUT을 사용하면서 프론트엔드가 실수로 닉네임만 보낸다면 백엔드 유효성 검증 실패로 400 Bad Request가 발생하거나 의도치 않게 연락처 데이터가 유실되는 위험에 직면하게 됩니다.
API 설계 실수 방지를 위한 PUT과 PATCH 결정 체크리스트
새로운 수정 엔드포인트를 정의할 때 실무에서 점검해야 할 선택 기준 체크리스트입니다. 첫째, 클라이언트가 리소스의 전체 표현(Full Representation)을 항상 온전하게 소유하고 있으며 이를 통째로 교체하려 하는지 확인합니다. 그렇다면 PUT이 적합합니다. 둘째, 화면 단위에서 일부 필드만 수정하는 비동기 입력이나 모바일 토글 인터랙션이 주를 이루는지 점검합니다. 필드 단위 갱신이 빈번하다면 PATCH를 선택하는 것이 네트워크와 서버 리소스 측면에서 훨씬 유리합니다.
셋째, 네트워크 불안정으로 인한 자동 재시도 환경을 고려해야 합니다. 통신 실패 시 클라이언트 라이브러리가 동일 요청을 재전송해도 서버 상태가 불변해야 하는 엄격한 멱등성 리소스라면 PUT을 우선 검토하거나 PATCH 처리 로직 내부를 멱등하게 설계해야 합니다. 마지막으로 팀 내 API 컨벤션에서 필드 누락 처리에 대한 명확한 규칙을 합의해야 합니다. PUT 엔드포인트에 부분 페이로드를 허용하는 변칙적인 구현은 API를 사용하는 동료 개발자에게 큰 혼란을 주므로 표준 명세에 맞추어 역할을 분리하는 것이 유지보수의 핵심입니다.
