Replace a resource with PUT

PUT으로 리소스 전체를 새 표현으로 교체하는 레시피입니다. 보낸 본문이 곧 리소스의 완전한 새 상태가 됩니다.

개요

PUT으로 리소스 전체를 새 표현으로 교체하는 레시피입니다. 보낸 본문이 곧 리소스의 완전한 새 상태가 됩니다.

코드로 보기

curl -X PUT https://api.example.com/users/1 \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada Lovelace","email":"ada@example.com","role":"admin"}'
await fetch('https://api.example.com/users/1', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Ada Lovelace',
    email: 'ada@example.com',
    role: 'admin'
  })
});
import requests

res = requests.put('https://api.example.com/users/1',
                   json={'name': 'Ada Lovelace',
                         'email': 'ada@example.com',
                         'role': 'admin'})
res.raise_for_status()

설명

PUT은 부분 수정이 아니라 전체 교체입니다. 본문에 포함하지 않은 필드는 서버 구현에 따라 삭제되거나 기본값으로 되돌아갈 수 있으므로, 모든 필드를 완전히 담아 보내야 합니다. 일부만 바꾸고 싶다면 PATCH를 쓰세요.

PUT은 멱등합니다. 같은 본문으로 여러 번 호출해도 최종 상태가 동일하므로, 네트워크 오류 시 안전하게 재시도할 수 있습니다.

결과 코드는 서버마다 다릅니다. 기존 리소스를 갱신하면 200(본문 있음) 또는 204(본문 없음)를, 지정한 URL에 리소스를 새로 만들면 201을 반환할 수 있습니다. 동시 수정 충돌을 막으려면 `If-Match: "<etag>"`로 낙관적 잠금을 걸어 409를 유도하세요.

관련 헤더

Content-TypeIf-Match

관련 상태코드

200OK204No Content201Created409Conflict