put patch 차이 (개념, 동작 방식, 장단점)

작성일자 글쓴이

웹 개발에서 RESTful API를 설계하거나 사용할 때, 클라이언트가 서버의 리소스를 수정하기 위해 주로 사용하는 두 가지 HTTP 메서드가 있습니다. 바로 PUT과 PATCH인데요. 이 둘은 모두 리소스를 업데이트한다는 점에서 비슷하지만, 동작 방식과 의도에 차이가 있어 상황에 맞게 선택하는 것이 중요합니다. 오늘은 PUT과 PATCH의 개념, 동작 방식, 장단점, 그리고 실제 API 설계 시 고려할 포인트를 상세히 살펴보겠습니다.

HTTP 메서드란?

HTTP 메서드는 클라이언트가 서버에 요청을 보낼 때 의도를 나타내는 키워드입니다.
주요 메서드로는 GET(읽기), POST(생성), PUT/PATCH(수정), DELETE(삭제) 등이 있습니다.
이 중 PUT과 PATCH는 모두 ‘리소스 업데이트’라는 유사한 목적을 갖지만, 내부 동작은 크게 다릅니다.

PUT 메서드

1. 개념 및 특징

  • 전체 대체: 클라이언트가 보내는 요청 페이로드(payload)는 해당 리소스의 ‘전체 표현(complete representation)’이어야 합니다.
  • 멱등성(Idempotency): 같은 PUT 요청을 여러 번 보내더라도 결과가 처음 한 번과 동일합니다.
  • 누락 필드 삭제: 요청 본문에 특정 필드가 빠지면, 서버는 이를 빈 값 혹은 기본값으로 대체하거나 삭제된 것으로 간주할 수 있습니다.

2. 사용 예시

PUT /users/123 HTTP/1.1
Content-Type: application/json

{
  "name": "김영희",
  "age": 28,
  "email": "younghee@example.com"
}

위 요청은 사용자(123번)의 모든 정보를 새로 덮어씌웁니다.
만약 email 필드가 없으면, 서버는 기존 이메일 정보를 지우거나 기본값으로 설정할 수 있습니다.

3. 장단점 요약

  • 장점: 구현이 단순하고, 멱등성 보장
  • 단점: 전체 데이터를 보내야 하므로 네트워크 부하가 크고, 일부 필드를 누락했을 때 의도치 않은 삭제가 발생할 수 있음

PATCH 메서드

1. 개념 및 특징

  • 부분 업데이트: 요청 페이로드에는 ‘변경하고자 하는 필드’만 포함합니다.
  • 비멱등성(Non-idempotent) 가능성: 일부 경우에는 같은 요청을 두 번 보내면 두 번째 요청이 추가로 변경을 가해 예상치 못한 결과를 낼 수 있습니다. 하지만, 설계에 따라 멱등성을 유지할 수도 있습니다.
  • 효율성: 필요한 데이터만 전송하므로 오버헤드가 적습니다.

2. 사용 예시

PATCH /users/123 HTTP/1.1
Content-Type: application/json

{
  "age": 29
}

위 요청은 사용자(123번)의 나이만 28→29로 업데이트하고, 나머지 정보(name, email 등)는 그대로 유지합니다.

3. 장단점 요약

  • 장점: 전송량 절감, 부분 변경만으로 안전한 업데이트 가능
  • 단점: 멱등성 보장 여부는 설계에 달려 있고, 복잡한 패치 문법(JSON Patch 등)을 사용할 때 학습 곡선이 있을 수 있음

PUT vs PATCH 비교

구분PUTPATCH
업데이트 범위전체 리소스 대체일부 필드만 수정
멱등성보장(동일 요청 반복 시 결과 동일)설계에 따라 다름
전송 데이터 크기크다(전체 표현)작다(부분 표현)
구현 난이도단순간혹 복잡(JSON Patch 등)
주요 사용 시나리오리소스를 완전히 교체하거나 초기화할 때리소스의 특정 속성만 변경할 때

API 설계 시 고려사항

  • 데이터 크기: 모바일 환경 등 대역폭이 제한된 상황에서는 PATCH를 선호
  • 멱등성 중요도: 결제·송금 시스템처럼 중복 요청이 치명적인 경우, 멱등성이 보장되는 PUT이 안전
  • 버전 관리: API 버전업 시 PUT과 PATCH의 동작 방식을 문서화하여 소비자가 혼동하지 않도록 함
  • 보안 및 검증: PATCH는 부분 업데이트이므로, 필드별 권한 검증이나 스키마 검증이 더 세밀히 필요

실전 코드 예제 (Node.js + Express)

// PUT 예제
app.put('/users/:id', async (req, res) => {
  const { id } = req.params;
  const newData = req.body;
  // 전체 교체: 누락된 필드는 삭제
  const updated = await User.replaceById(id, newData);
  res.json(updated);
});

// PATCH 예제
app.patch('/users/:id', async (req, res) => {
  const { id } = req.params;
  const partialData = req.body;
  // 부분 업데이트: 존재하는 필드만 수정
  const updated = await User.updateFields(id, partialData);
  res.json(updated);
});

PUT과 PATCH는 리소스를 수정한다는 공통점이 있지만, 전체 대체냐 부분 수정이냐에 따라 목적과 사용 방법이 크게 달라집니다.
API를 설계할 때는 서비스 특성과 트래픽 상황, 멱등성 보장 여부 등을 종합적으로 고려하여 두 메서드를 적절히 활용하세요.

오늘 내용이 HTTP PUT과 PATCH의 차이를 이해하고, 실무 API 설계에 적용하는 데 도움이 되었길 바랍니다.