PUT
The HTTP PUT method creates or replaces a resource at the target URI with the representation enclosed in the request body.
Usage
A PUT request tells the server to store the enclosed representation at the specified URI. If the resource already exists, the server replaces its entire state with the new representation. If no resource exists at the URI, the server creates one.
Idempotency
PUT is idempotent. Sending the same PUT request multiple times produces the same server state as sending the request once. This contrasts with POST, where repeated submissions create duplicate resources or trigger processing multiple times.
Idempotency makes PUT safe to retry after network failures. A client unsure whether a previous request arrived sends the request again without risking unintended side effects.
Content negotiation
The server validates the incoming representation against its own constraints. When the Content-Type matches expectations and the content is well-formed, the server stores the resource and responds with 201 Created for new resources or 200 OK / 204 No Content for replacements.
When the media type is incompatible, the server returns 415 Unsupported Media Type. A 409 Conflict response indicates a state conflict unrelated to content type, such as a version mismatch.
PUT vs POST
POST delegates processing to the target
resource. PUT specifies the exact URI where the
representation belongs. A PUT to /articles/42
stores the article at /articles/42. A POST to
/articles asks the collection to create a new article
at a server-chosen URI.
PUT vs PATCH
PUT replaces the entire resource. PATCH applies partial modifications. Updating a single field with PUT requires sending the full representation. PATCH sends only the changes.
Properties
| Property | Value |
|---|---|
| Safe | No |
| Idempotent | Yes |
| Cacheable | No |
Example
Creating a resource
A client stores a plain text file at /docs/setup.txt.
The server creates the resource and responds with
201 Created.
Request
PUT /docs/setup.txt HTTP/1.1
Host: api.example.re
Content-Type: text/plain
Content-Length: 24
Install, configure, run.
Response
HTTP/1.1 201 Created
Location: /docs/setup.txt
Content-Length: 0
Replacing a resource
A client replaces an existing JSON resource at
/users/42. The server confirms the update with
200 OK and returns the stored representation.
Request
PUT /users/42 HTTP/1.1
Host: api.example.re
Content-Type: application/json
Content-Length: 43
{"name":"Alice","email":"alice@example.re"}
Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 51
{"id":42,"name":"Alice","email":"alice@example.re"}
Conditional update
A client sends an If-Match header to prevent overwriting a resource modified by another client. The ETag value ensures the update applies only to the expected version.
Request
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}
Response
HTTP/1.1 204 No Content
ETag: "d4e5f6"
Takeaway
The HTTP PUT method creates or replaces a resource at a specific URI. The request is idempotent, making retries safe after failures. The server validates the representation and returns the appropriate status based on whether the resource was created or replaced.
