write
HTTP PUT
Replaces the target resource entirely with the request payload, or creates it if it does not exist at the given URL. The client dictates the resource identifier, so PUT is idempotent.
PUT /path/{id} HTTP/1.1Properties
| Property | Value / Meaning |
|---|---|
| Safe | No - PUT modifies or creates the resource at the target URL. |
| Idempotent | Yes - PUTting the same body N times leaves the resource in the same final state. |
| Cacheable | No - PUT responses are not cached; caches must invalidate the URL instead. |
| Has body | Yes - the body is the complete new representation of the resource. |
| Body in response | Optional - often 200/204 with no body, or 201 with the created resource. |
Examples
curl -X PUT -H 'Content-Type: application/json' -d '{"name":"Ada","role":"admin"}' https://api.example.com/users/42Replace user 42 entirely with the given object.
curl -X PUT --upload-file ./config.yaml https://api.example.com/configs/prodUpload a file as the full resource body.
curl -X PUT -H 'If-Match: "abc123"' -d '{...}' https://api.example.com/users/42Optimistic concurrency using an ETag.
PUT /docs/readme HTTP/1.1\nHost: files.example.com\nContent-Type: text/markdown\n\n# HelloRaw PUT creating or replacing a document.
Gotcha
PUT replaces the entire resource - fields omitted from the body are removed. Use PATCH for partial updates. Always require If-Match with ETags to avoid lost-update races.
Related methods
HTTP PATCH
Applies a partial modification to a resource, described by the patch document in the request body (e.g. JSON Patch or JSON Merge Patch). Only the specified fields change; the rest of the resource is untouched.
HTTP POST
Submits an entity to the specified resource, often causing a change in state or side effect on the server. Used for creating resources, form submissions, and RPC-style calls.
HTTP DELETE
Removes the target resource, or requests its removal. Once deleted, subsequent requests typically return 404 or 410.
HTTP COPY
WebDAV extension (RFC 4918) that copies a resource from the Request-URI to the URI given in the Destination header. Can copy collections recursively based on the Depth header.
HTTP MOVE
WebDAV extension (RFC 4918) that moves a resource from the Request-URI to the Destination URI, equivalent to a COPY followed by a DELETE of the source. Preserves the resource across the rename or relocation.