POST
The HTTP POST method sends data to a server to create a resource or trigger processing on the target resource.
Usage
A POST request submits an entity to the specified resource. The server determines how to handle the enclosed representation based on the resource's own semantics. Unlike PUT, which targets a specific resource URI, POST delegates processing to the resource identified by the target URI.
The Content-Type header indicates the format of the request body. Three encodings are common in HTML forms and APIs.
application/x-www-form-urlencoded
The default encoding for HTML forms. Data is structured
as key-value pairs separated by ampersands (&), with
keys and values joined by equals signs (=).
Non-alphanumeric characters use
Percent-Encoding.
name=Alice&role=admin
multipart/form-data
Each field occupies a separate part delimited by a boundary string declared in the Content-Type header. This encoding supports binary data such as file uploads. The Content-Disposition header within each part names the field.
text/plain
No prescribed structure. The server processes the raw body according to its own logic.
Repeated POST requests are not idempotent. Submitting the same form twice creates two resources or triggers processing twice, unlike PUT where a repeated request produces the same server state.
POST responses are cacheable only when the response includes explicit freshness information and a matching Content-Location header.
Properties
| Property | Value |
|---|---|
| Safe | No |
| Idempotent | No |
| Cacheable | Conditional |
Example
Form submission
A client submits form data using URL-encoded format. The server creates a job and responds with 201 Created.
Request
POST /jobs HTTP/1.1
Host: api.example.re
Content-Type: application/x-www-form-urlencoded
Content-Length: 17
name=backup&pri=2
Response
HTTP/1.1 201 Created
Location: /jobs/47
Content-Type: application/json
Content-Length: 38
{"id":47,"name":"backup","priority":2}
Multipart file upload
A client uploads a file using multipart encoding. The
boundary string ----Boundary separates each part. The
server accepts the upload and returns
202 Accepted.
Request
POST /uploads HTTP/1.1
Host: api.example.re
Content-Type: multipart/form-data; boundary=----Boundary
Content-Length: 196
------Boundary
Content-Disposition: form-data; name="title"
Q4 Report
------Boundary
Content-Disposition: form-data; name="file"; filename="report.pdf"
Content-Type: application/pdf
<binary data>
------Boundary--
Response
HTTP/1.1 202 Accepted
Location: /uploads/91
Content-Length: 0
JSON API
A client sends a JSON payload to create a new user. The
server returns the created resource with an id field.
Request
POST /users HTTP/1.1
Host: api.example.re
Content-Type: application/json
Content-Length: 41
{"email":"alice@example.re","role":"ops"}
Response
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 50
{"id":112,"email":"alice@example.re","role":"ops"}
Takeaway
The HTTP POST method sends data for server-side processing. The request is neither safe nor idempotent, and the server's response depends on the resource semantics and the Content-Type of the submitted body.
