POST method
POST asks the target resource to process enclosed content according to that resource's semantics.
- methods
- request content
Defined meaning
POST asks the target resource to process the enclosed representation according
to the resource’s own semantics. Common uses include submitting data, creating a
resource through a collection, appending data, and triggering an operation.
POST /messages HTTP/1.1
Host: example.invalid
Content-Type: text/plain
Content-Length: 5
hello
Expected result: /messages defines how hello is processed. Creation can be
reported with 201 Created and Location; another valid application can return a
different status matching its result.
Properties
POST is not safe and is not idempotent by definition. Application-level idempotency keys can deduplicate repeated processing or make an application operation idempotent under a documented private contract. They do not make POST an HTTP safe method or change its registered method properties.
POST responses are cacheable only when they carry explicit freshness information
and a Content-Location value equal to the POST target URI. Such a stored
response can satisfy a later GET or HEAD request, but it cannot satisfy another
POST request. Many caches do not implement this reuse.
Common mistake
Do not use a redirect code with historical method rewriting when the follow-up must preserve POST and its content. Choose the redirect semantics deliberately.