The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →PUT replaces a resource with the complete representation you send; PATCH applies a defined set of changes to an existing resource. PUT is idempotent by HTTP method definition, while PATCH is not inherently idempotent. Choose based on whether your client is declaring the entire desired state or describing a transformation, then protect either operation with validators such as ETags when stale clients could overwrite newer data.
The direct comparison
| Axis | PUT | PATCH |
|---|---|---|
| Payload meaning | Complete replacement representation | Change instructions or a partial representation defined by the patch format |
| Typical scope | Replace the resource at a known URI; may create it when no current representation exists | Modify selected parts of an existing resource; creation depends on the patch format and server rules |
| Idempotency | Idempotent by HTTP method definition | Not inherently idempotent; an individual patch can be designed to be idempotent |
| Retry posture | Identical retries generally have the same intended effect | Retry only when the operation and concurrency strategy make repetition safe |
| Concurrency | Use ETags and conditional requests when replacement could overwrite newer state | Use a strong ETag with If-Match when the patch depends on a particular version |
| Atomicity | The requested replacement is the target state | The complete change set must be applied all at once or not at all |
What PUT means
RFC 9110 (June 2022) defines PUT as a request for the target resource’s state to be created or replaced by the representation in the request content. The client normally knows the target URI. If the server should choose a new URI after receiving a representation, POST is generally the appropriate method instead.
Complete representation, not an automatic merge
A PUT body should describe the final state you want at that URI. Consider a profile resource:
PUT /users/42 HTTP/1.1
Content-Type: application/json
{"name":"Amina","email":"[email protected]","timezone":"UTC"}If the existing profile also has a phone field, whether omitting it deletes, preserves, or rejects that field is an application-contract decision. HTTP’s replacement semantics do not define your database merge rules. Document required fields and the meaning of omitted and null properties.
#1 Best Overall
Creation and replacement
A server may create a representation at the requested URI if none exists, or replace the current representation. The response commonly indicates whether a new resource was created or an existing one changed, but your API should document its exact status-code behavior.
What PATCH means
RFC 5789 (March 2010) defines PATCH for partial modification. The request entity contains instructions for transforming the resource currently held by the origin server. PATCH itself does not prescribe one JSON shape.
The patch media type is part of the contract
One API might accept a merge-style object:
PATCH /users/42 HTTP/1.1
Content-Type: application/merge-patch+json
{"timezone":"Europe/Paris"}Another might require JSON Patch’s operation list:
PATCH /users/42 HTTP/1.1
Content-Type: application/json-patch+json
[{"op":"replace","path":"/timezone","value":"Europe/Paris"}]The media type and documentation must define how nulls, omitted properties, arrays, invalid paths, and conflicting edits behave. Do not assume that a plain JSON object always means “merge these fields.”
Rank #2
- Used Book in Good Condition
Does PATCH create resources?
Creation depends on the patch format and server rules. Unlike PUT, PATCH has no general method-level promise that a missing target will be created. State this explicitly in your API documentation.
Idempotency, safety, and retries
PUT is idempotent, not safe
HTTP idempotency concerns the intended effect of repeating an identical request. PUT is idempotent: sending the same complete representation repeatedly is intended to leave the resource in the same requested state. A server can still record audit entries, consume rate limits, or trigger other side effects for each request.
Idempotent does not mean safe or read-only. PUT changes server state; MDN classifies it as not safe.
PATCH can be idempotent by design
RFC 5789 says PATCH is neither safe nor inherently idempotent, but a particular patch can be issued idempotently. A “set status to paid” operation can usually be repeated harmlessly. An “increment balance by 10” operation cannot, unless the API supplies a request identifier or another deduplication mechanism.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Before automatically retrying PATCH, determine whether repeating every operation has the same result, whether the server supports idempotency keys, and whether your conditional request will reject a stale base version.
Concurrency: prevent lost updates
Suppose two clients read version 7. Client A changes the email; client B changes the timezone. A complete PUT from B can unintentionally erase A’s email change. A PATCH can also conflict when an operation assumes fields or array positions from an old representation.
ETag and If-Match workflow
- GET the resource and retain its strong
ETag, such as"v7". - Send the update with
If-Match: "v7". - Have the server apply the request only if that exact current representation still matches.
- Return a precondition failure (commonly
412 Precondition Failed) when another write changed the resource; the client can fetch the new version, reconcile, and retry deliberately.
PATCH /users/42 HTTP/1.1
If-Match: "v7"
Content-Type: application/merge-patch+json
{"timezone":"Europe/Paris"}RFC 5789 specifically recommends a strong ETag with If-Match when a PATCH must be based on a known representation. The same validator discipline is useful for PUT replacements. Validators returned after a successful PUT can protect subsequent updates.
Atomic PATCH processing
RFC 5789 requires the server to process a PATCH document atomically: if any part of the complete change set cannot be applied, none of its changes may be applied. For a multi-operation JSON Patch, do not persist the first operations and then return an error for a later one.
Partial PUT and Content-Range
Some servers support a partial PUT using Content-Range, but RFC 9110 notes that this is inconsistent and depends on private agreements. It is not backward-compatible with ordinary PUT: a server without that agreement may treat the request as a complete replacement. For interoperable partial updates, use PATCH with a documented format rather than assuming Content-Range turns PUT into a merge.
Practical decision rule
- Use PUT when the client can construct the complete desired representation for a known resource URI and replacement semantics are intended.
- Use PATCH when only selected fields change or the operation is naturally expressed as instructions.
- Document the patch media type and exact behavior for omitted fields, nulls, arrays, validation errors, and missing targets.
- Use
ETag/If-Matchor an equivalent concurrency policy whenever stale clients could overwrite newer state. - Test repeated requests, validation failures, conflict responses, and atomic rollback before exposing automatic retries.
Runnable examples
cURL
curl -i -X PUT https://api.example.com/users/42
-H 'Content-Type: application/json'
-H 'If-Match: "v7"'
--data '{"name":"Amina","email":"[email protected]","timezone":"UTC"}'
curl -i -X PATCH https://api.example.com/users/42
-H 'Content-Type: application/merge-patch+json'
-H 'If-Match: "v7"'
--data '{"timezone":"Europe/Paris"}'Python
import requests
url = "https://api.example.com/users/42"
headers = {"If-Match": '"v7"'}
put = requests.put(url, headers={**headers, "Content-Type": "application/json"},
json={"name": "Amina", "email": "[email protected]", "timezone": "UTC"}, timeout=30)
put.raise_for_status()
patch = requests.patch(url, headers={**headers, "Content-Type": "application/merge-patch+json"},
json={"timezone": "Europe/Paris"}, timeout=30)
patch.raise_for_status()Node.js
const url = 'https://api.example.com/users/42';
const common = { 'If-Match': '"v7"' };
const put = await fetch(url, {
method: 'PUT',
headers: { ...common, 'Content-Type': 'application/json' },
body: JSON.stringify({ name: 'Amina', email: '[email protected]', timezone: 'UTC' })
});
if (!put.ok) throw new Error(`PUT failed: ${put.status}`);
const patch = await fetch(url, {
method: 'PATCH',
headers: { ...common, 'Content-Type': 'application/merge-patch+json' },
body: JSON.stringify({ timezone: 'Europe/Paris' })
});
if (!patch.ok) throw new Error(`PATCH failed: ${patch.status}`);Troubleshooting common failures
Fields disappear after PUT
Your server is enforcing replacement semantics or interpreting omission as deletion. Send the complete representation, or change the endpoint contract to a documented PATCH format.
PATCH returns 415 Unsupported Media Type
The body’s patch format is not accepted. Check the endpoint’s required Content-Type, such as application/merge-patch+json or application/json-patch+json.
PATCH returns 409 or 412
The change conflicts with current state or your ETag is stale. Fetch the latest representation, reconcile the intended change, and send a new conditional request.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsBest Value
A retry duplicates an action
The patch was not idempotent. Avoid blind retries for increments, appends, or toggles; use idempotency keys or redesign the operation as an absolute “set” where appropriate.
Several patch operations partially succeeded
That violates the required atomic behavior. Treat it as a server defect: apply the document transactionally and return an error without persisting any operation when one fails.
Or skip the browser setup
When you need screenshots of API documentation, test fixtures, or rendered responses, ScreenshotNeo provides a single-call website screenshot API. It accepts cookie banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; failed loads, blank pages, bot checks, timeouts, and cache hits are not billed. Its MCP server gives AI agents tools for screenshots, page information, and PDFs.
cURL (see the ScreenshotNeo docs):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
Free tools Windows power users keep installed
One-click scans. No signup required.
Frequently Asked Questions
Can I use PUT for a partial update?
Only if that specific server documents nonstandard partial-PUT behavior. For interoperable partial updates, use PATCH with its stated media type.
Which method should a form use to edit one field?
Use PATCH when the operation changes only that field; use PUT when the client submits the complete intended representation.
Should every PATCH request include If-Match?
Include it whenever applying a stale change could overwrite or conflict with another client’s edit. APIs may choose another explicit concurrency policy for cases where that risk does not exist.
What should an API document for PATCH?
Document the accepted patch media type, operation syntax, omitted and null fields, array behavior, missing-resource rules, validation and conflict responses, atomicity, and retry or idempotency guarantees.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
