PUT vs POST vs PATCH: Quick Answer

REST API PUT vs POST vs PATCH decisions should follow HTTP semantics: POST asks a target resource to process content, PUT creates or replaces the state of a known target, and PATCH applies a defined set of partial changes.

The most important difference is the meaning of the request representation. With PUT, the representation describes the desired replacement state of the target resource. With PATCH, it describes changes to apply. With POST, the target processes the representation according to that resource’s own semantics.

REST API POST Example

Use POST when the server determines the URI for a newly created resource or when the request represents a command/process rather than complete replacement of the target.

POST /v1/orders HTTP/1.1
Content-Type: application/json

{
  "customer_id": "cus_42",
  "items": [{"sku":"SKU-1","quantity":2}]
}

HTTP/1.1 201 Created
Location: /v1/orders/ord_900
Content-Type: application/json

{"id":"ord_900","status":"created"}

Because POST is not inherently idempotent, a retry after a connection failure can create a second order unless the API provides a safe-retry mechanism such as an idempotency key.

REST API PUT Example

PUT targets a known resource URI and asks the server to create or replace the current representation with the supplied state:

PUT /v1/user-preferences/usr_7 HTTP/1.1
Content-Type: application/json

{
  "language": "en",
  "timezone": "Asia/Jerusalem",
  "email_notifications": true
}

If the resource did not exist and PUT creates it, RFC 9110 requires 201 Created. If an existing resource is replaced successfully, 200 OK or 204 No Content are common depending on whether a response representation is returned.

REST API PATCH Example

PATCH applies partial modifications. The request body is a patch document whose media type defines how changes are interpreted.

PATCH /v1/users/usr_7 HTTP/1.1
Content-Type: application/merge-patch+json
If-Match: "user-v12"

{
  "email_notifications": false
}

PATCH is especially useful when representations are large or when clients should be able to update a small subset without sending the entire resource. Use conditional requests such as If-Match with ETags when lost updates are a risk.

RFC 5789 also defines Accept-Patch, which a server can expose (for example in an OPTIONS response) to advertise patch document media types it supports.

Accept-Patch: application/merge-patch+json, application/json-patch+json

PUT vs POST vs PATCH by Common API Scenario

PUT, POST, PATCH and Idempotency

HTTP defines PUT as idempotent. POST and PATCH are not inherently idempotent, although an API can design a specific operation or patch format so retries are safe. Do not infer idempotency from whether the server happens to return the same response today.

For retry-safe creation operations, see Idempotency API examples and best practices.

Typical HTTP Status Codes for PUT, POST and PATCH

• 201 Created: a new resource was created, commonly by POST or by PUT to a previously nonexistent target.
• 200 OK: operation succeeded and a representation is returned.
• 204 No Content: operation succeeded and no response body is needed.
• 409 Conflict: request conflicts with current resource/application state.
• 412 Precondition Failed: an If-Match or other precondition failed, useful for optimistic concurrency.
• 415 Unsupported Media Type: request uses a patch or representation media type the endpoint does not accept.

For a broader status-code reference, see API failure and HTTP status codes explained.

Security Considerations for State-Changing Methods

• Authorize the target object and action separately; permission to read a resource does not imply permission to PUT or PATCH it.
• Reject unknown or non-writable properties to reduce mass-assignment risk.
• Validate content type and request schema before applying changes.
• Use optimistic concurrency where two clients can overwrite each other.
• Rate-limit expensive or sensitive state changes and log high-risk transitions.
• Do not assume “idempotent” means harmless: repeated DELETE or PUT calls can still be abusive.

Common PUT, POST and PATCH Mistakes

• Using POST for every state change because the framework makes it easy.
• Implementing PUT as partial update and surprising clients that expect replacement semantics.
• Using PATCH with an undocumented ad-hoc body format.
• Allowing PATCH to modify server-managed or privileged fields.
• Returning 200 for every failure and placing the real error only inside JSON.
• Ignoring concurrency and silently overwriting changes made by another client.

JSON Merge Patch vs JSON Patch

PATCH does not define one universal JSON body. The media type tells the server what the patch document means. Two established approaches are JSON Merge Patch (application/merge-patch+json) and JSON Patch (application/json-patch+json).

A custom DTO can be safer than exposing a fully generic patch language when only a handful of fields are meant to change. Whatever format you choose, publish the media type and semantics explicitly.

Do not label an ordinary partial JSON object as “JSON Patch” unless it actually follows RFC 6902. Likewise, JSON Merge Patch has specific null semantics defined by RFC 7396.

Preventing Lost Updates with ETags and Preconditions

PUT and PATCH can overwrite another client’s changes if both read the same version and then write independently. HTTP conditional requests provide a clean optimistic-concurrency pattern: return an ETag with the resource and require If-Match on updates.

GET /v1/users/usr_7

200 OK
ETag: "user-v12"

PATCH /v1/users/usr_7
If-Match: "user-v12"
Content-Type: application/merge-patch+json

{"email_notifications":false}

If the current resource no longer matches that validator, return 412 Precondition Failed and let the client refresh before deciding whether to reapply its change. This is often safer than last-write-wins behavior for administrative or financial objects.

How Ammune Fits

Correct HTTP method semantics make an API predictable, but attackers can still call perfectly valid methods in abusive sequences. Ammune observes runtime API behavior so teams can identify unusual update frequency, mass modification, authorization abuse or unexpected method usage while application code enforces the actual resource semantics.

Production Implementation Checklist

• Define method semantics from resource intent, not CRUD naming alone.
• Use POST when the target processes an action or server selects a new resource URI.
• Use PUT for create/replace at a known target URI.
• Use PATCH for documented partial-modification semantics.
• Publish accepted PATCH media types.
• Validate writable fields and reject mass-assignment attempts.
• Use idempotency for retryable POST operations where duplicates matter.
• Use ETag/If-Match when lost updates are possible.
• Return HTTP status codes that match protocol outcomes.
• Test retries, concurrent updates and unauthorized field changes.

Frequently Asked Questions

Primary References