HTTP 자원의 전체 교체와 일부 수정, PUT과 PATCH는 어떻게 다를까

PUT은 요청 표현으로 대상 자원의 상태를 생성하거나 대체하는 메서드입니다. PATCH는 서버가 기존 자원에 적용할 변경 지시를 전달하는 메서드이므로, 요청 본문은 전체 자원이 아니라 변경 내용일 수 있습니다.

PATCH가 언제나 멱등이거나 특정 JSON 형식이라는 뜻은 아닙니다. 반복 적용 결과는 패치 문서와 서버의 적용 방식에 달려 있습니다.

요청 본문의 의미부터 구분합니다

HTTP 메서드를 고를 때는 화면에서 몇 칸을 수정했는지만 보지 말고, 서버가 요청 본문을 어떤 계약으로 해석해야 하는지 확인해야 합니다. RFC 9110의 PUT은 대상 자원의 현재 상태를 요청 표현으로 생성하거나 대체하라는 의미입니다. RFC 5789는 PATCH를 기존 자원을 수정하는 방법으로 설명하며, 완전한 문서 교체를 뜻하는 PUT만으로는 표현하기 어려운 부분 변경을 위해 도입했습니다. 따라서 두 메서드의 차이는 단순히 URL이나 본문 길이가 아니라, 본문이 전체 표현인지 변경 지시인지에 있습니다.

프로필 전체와 알림 설정 한 칸을 비교합니다

사용자 프로필이 이름, 이메일, 알림 설정을 가진다고 해 보겠습니다. 클라이언트가 자원의 완전한 표현을 알고 있고 이름만 바꾼 새 상태를 보낼 때는 PUT 본문에 나머지 필드도 포함해 대체 계약을 분명히 할 수 있습니다. 반면 서버가 정한 패치 형식이 알림 설정만 바꾸도록 되어 있다면 PATCH 본문에는 그 변경 지시만 보낼 수 있습니다. 다음 JSON 모양은 이해를 위한 창작 예시이며, RFC가 특정 필드 이름이나 JSON Patch 문법을 정해 주는 것은 아닙니다.

PUT /users/42/profile HTTP/1.1
Content-Type: application/json

{"name":"민서","email":"minseo@example.test","notifications":true}

PATCH /users/42/profile HTTP/1.1
Content-Type: application/merge-patch+json

{"notifications":false}

표의 ‘일반적’이라는 표현은 서비스의 실제 스키마가 자동으로 정해진다는 뜻이 아닙니다. 예를 들어 어떤 API는 PUT 본문에서 빠진 필드를 기본값으로 처리하고, 다른 API는 누락을 오류로 거부할 수 있습니다. 클라이언트와 서버가 합의한 표현을 확인해야 합니다. 마찬가지로 PATCH의 본문 형식과 적용 규칙도 API 계약을 읽어야 알 수 있습니다. Content-Type만 보고 모든 서버가 같은 패치 동작을 한다고 가정하지 마세요.

요청을 만들기 전에 다섯 가지를 점검합니다

1. 변경 대상이 하나의 HTTP 자원인지 식별합니다.
2. 서버가 기대하는 요청 표현의 범위를 확인합니다.
3. 전체 상태를 보낼 수 있으면 PUT 계약을 검토하고, 부분 변경 문서를 지원하면 PATCH를 검토합니다.
4. PATCH의 media type, 누락 필드, null 처리와 반복 적용 규칙을 API 문서에서 확인합니다.
5. 동시 수정이 문제라면 ETag와 If-Match 같은 사전조건을 별도로 설계합니다.

마지막 점검이 중요한 까닭은 PUT이나 PATCH를 골랐다는 사실만으로 동시 수정 충돌이 해결되지 않기 때문입니다. 두 사용자가 같은 자원을 읽고 거의 동시에 바꾸면, 서버가 충돌을 어떻게 검출하는지 별도 규칙이 필요합니다. 조건부 요청을 사용하거나 서버에서 버전 검사를 둘 수 있습니다. 또한 브라우저 폼에서 필드 하나만 바뀌었다고 자동으로 PATCH를 보내야 하는 것도 아닙니다. 서버 계약이 전체 교체를 요구하면 클라이언트가 현재 전체 표현을 구성해 PUT을 사용할 수 있습니다.

PATCH를 ‘항상 부분 필드 저장’이라고 단정하지 않습니다

흔한 오해는 PATCH가 늘 JSON 한 필드만 전달하는 메서드이고, 같은 요청을 다시 보내도 결과가 반드시 같다고 생각하는 것입니다. RFC 5789는 패치 문서가 자원에 적용되는 방법을 정의하며, 문서의 형식은 요청의 media type과 서버 지원에 따라 달라집니다. 예를 들어 값을 특정 값으로 설정하는 변경과 현재 값에 1을 더하는 변경은 반복했을 때 결과가 다를 수 있습니다. PATCH는 멱등일 수도 있지만, 메서드 이름만으로 멱등성이 보장되지는 않습니다. 반복 요청을 재시도할 수 있는지 판단할 때 실제 패치 명령의 효과를 살펴야 합니다.

현재 조회 수: 10
PATCH 명령: 조회 수에 1을 더한다
첫 적용 뒤: 11
같은 명령을 다시 적용한 뒤: 12

반대로 notifications를 false로 설정하는 패치가 서버에서 그 값 대입만 수행한다면 같은 요청의 반복 결과는 같을 수 있습니다. 그러나 이것도 해당 API의 정의와 다른 부수 효과가 없는지에 달렸습니다. 시험에서는 ‘PUT은 전체 대체 의미, PATCH는 부분 수정 의미’를 핵심으로 잡고, ‘PUT은 모든 서버에서 필수 필드를 전부 전송해야 한다’처럼 구체 구현을 보편 규칙으로 과장하지 않는 것이 안전합니다.