Partially update with PATCH

PATCH로 리소스의 일부 필드만 부분 수정하는 레시피입니다. 바꾸려는 필드만 보내면 나머지는 그대로 유지됩니다.

개요

PATCH로 리소스의 일부 필드만 부분 수정하는 레시피입니다. 바꾸려는 필드만 보내면 나머지는 그대로 유지됩니다.

코드로 보기

curl -X PATCH https://api.example.com/users/1 \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{"role":"editor"}'
await fetch('https://api.example.com/users/1', {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/merge-patch+json' },
  body: JSON.stringify({ role: 'editor' })
});
import requests

res = requests.patch('https://api.example.com/users/1',
                     headers={'Content-Type': 'application/merge-patch+json'},
                     json={'role': 'editor'})
res.raise_for_status()

설명

가장 흔한 형식은 JSON Merge Patch(RFC 7396)로, `Content-Type: application/merge-patch+json`을 씁니다. 보낸 키만 덮어쓰고, 값에 `null`을 주면 해당 필드를 삭제합니다. 더 정밀한 연산이 필요하면 JSON Patch(RFC 6902, `application/json-patch+json`)로 add/remove/replace 같은 연산 배열을 보냅니다.

PATCH는 표준상 멱등을 보장하지 않습니다. 예를 들어 카운터 증가 같은 상대적 연산은 반복 시 결과가 달라지므로, 재시도 안전성이 필요하면 절대값 지정 방식이나 `If-Match`를 함께 사용하세요.

전체 필드를 다 보내야 하는 PUT과 달리 PATCH는 전송량이 적고 필드 누락으로 인한 의도치 않은 초기화 위험이 없어, 폼의 일부 저장 같은 UI에 적합합니다.

관련 헤더

Content-TypeIf-Match

관련 상태코드

200OK204No Content409Conflict422Unprocessable Content