write
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.
POST /path HTTP/1.1Properties
| Property | Value / Meaning |
|---|---|
| Safe | No - POST typically creates or triggers something on the server. |
| Idempotent | No - submitting the same POST twice may create two resources or charge a card twice. |
| Cacheable | Rarely - only when the response explicitly sets Cache-Control or Expires. |
| Has body | Yes - the payload carries the data being submitted (JSON, form, multipart). |
| Body in response | Usually - typically returns the created resource or a status envelope. |
Examples
curl -X POST -H 'Content-Type: application/json' -d '{"name":"Ada"}' https://api.example.com/usersCreate a new user with a JSON body.
curl -X POST -F '[email protected]' https://api.example.com/uploadsmultipart/form-data file upload.
curl -X POST --data-urlencode 'q=http methods' https://api.example.com/searchapplication/x-www-form-urlencoded submission.
POST /orders HTTP/1.1\nHost: shop.example.com\nContent-Type: application/json\nContent-Length: 27\n\n{"sku":"A1","qty":2}Raw HTTP POST creating an order.
Gotcha
Because POST is not idempotent, use an Idempotency-Key header or client-generated UUID for retries. Do not use POST for reads just to hide query params from logs - it breaks caching and REST semantics.
Related methods
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.
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 GET
Requests a representation of the specified resource. It is the most common HTTP method and should have no side effects on the server.
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.