PUT

사용법

PUT 요청은 담겨 온 표현을 지정된 URI에 저장하라고 서버에 지시합니다. 리소스가 이미 존재하면 서버는 그 상태 전체를 새 표현으로 교체합니다. 해당 URI에 리소스가 없으면 서버가 새로 만듭니다.

멱등성

PUT은 멱등합니다. 같은 PUT 요청을 여러 번 보내도 서버 상태는 한 번 보냈을 때와 같습니다. 이는 제출을 반복하면 리소스가 중복 생성되거나 처리가 여러 번 일어나는 POST와 대비됩니다.

멱등성 덕분에 PUT은 네트워크 장애 이후 안전하게 재시도할 수 있습니다. 이전 요청이 도달했는지 확신할 수 없는 클라이언트는 의도치 않은 부수 효과를 걱정하지 않고 요청을 다시 보낼 수 있습니다.

콘텐츠 협상

서버는 들어온 표현을 자체 제약 조건과 대조해 검증합니다. Content-Type이 기대와 맞고 콘텐츠의 형식도 올바르면, 서버는 리소스를 저장하고 새 리소스에는 201 Created로, 교체에는 200 OK 또는 204 No Content로 응답합니다.

미디어 타입이 호환되지 않으면 서버는 415 Unsupported Media Type을 반환합니다. 409 Conflict 응답은 버전 불일치처럼 콘텐츠 타입과 무관한 상태 충돌을 나타냅니다.

PUT과 POST 비교

POST는 처리를 대상 리소스에 위임합니다. PUT은 그 표현이 속할 정확한 URI를 지정합니다. /articles/42에 대한 PUT은 그 글을 /articles/42에 저장합니다. /articles에 대한 POST는 해당 컬렉션에 서버가 선택한 URI로 새 글을 만들어 달라고 요청합니다.

PUT과 PATCH 비교

PUT은 리소스 전체를 교체합니다. PATCH는 부분적인 수정을 적용합니다. PUT으로 필드 하나를 갱신하려면 표현 전체를 보내야 합니다. PATCH는 변경 사항만 보냅니다.

리소스 생성

클라이언트가 평문 텍스트 파일을 /docs/setup.txt에 저장합니다. 서버는 리소스를 생성하고 201 Created로 응답합니다.

요청

PUT /docs/setup.txt HTTP/1.1
Host: api.example.re
Content-Type: text/plain
Content-Length: 24

Install, configure, run.

응답

HTTP/1.1 201 Created
Location: /docs/setup.txt
Content-Length: 0

리소스 교체

클라이언트가 /users/42에 있는 기존 JSON 리소스를 교체합니다. 서버는 200 OK로 갱신을 확인해 주고 저장된 표현을 반환합니다.

요청

PUT /users/42 HTTP/1.1
Host: api.example.re
Content-Type: application/json
Content-Length: 43

{"name":"Alice","email":"alice@example.re"}

응답

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 51

{"id":42,"name":"Alice","email":"alice@example.re"}

조건부 갱신

If-Match를 사용하는 조건부 요청은 다른 클라이언트가 수정한 리소스를 덮어쓰는 일을 막아 줍니다. ETag 값은 갱신이 기대한 버전에만 적용되도록 보장합니다.

요청

PUT /config/app.json HTTP/1.1
Host: api.example.re
Content-Type: application/json
If-Match: "a1b2c3"
Content-Length: 27

{"debug":false,"port":8080}

응답

HTTP/1.1 204 No Content
ETag: "d4e5f6"

CORS

교차 출처 PUT 요청은 언제나 CORS 프리플라이트를 유발합니다. 브라우저는 서버가 대상 리소스에 PUT을 허용하는지 확인하기 위해 먼저 OPTIONS 요청을 보냅니다.

응답 상태 코드

201 Created는 서버가 대상 URI에 새 리소스를 생성했음을 나타냅니다. 그 위치에 이전에 리소스가 없었던 경우에 해당합니다.

200 OK는 기존 리소스가 교체되었음을 확인해 주며, 응답 본문에 갱신된 표현이 포함됩니다.

204 No Content는 응답 본문 없이 교체가 이루어졌음을 확인해 줍니다. 클라이언트가 저장된 표현을 되돌려받을 필요가 없을 때 흔합니다.

412 Precondition Failed는 If-Match 조건이 충족되지 않았음을 나타냅니다. 클라이언트가 제공한 ETag 값이 현재 리소스 버전과 일치하지 않으므로, 서버는 다른 클라이언트가 가한 변경을 덮어쓰지 않도록 갱신을 거부합니다.

409 Conflict는 전제 조건과 무관한 애플리케이션 수준의 상태 충돌을 알립니다. 콘텐츠 병합 충돌이나 클라이언트가 수동으로 해소해야 하는 버전 관리 충돌 같은 경우입니다.