POST
The POST method submits a payload for processing by the target resource. The POST method has few defined semantics, and can be used to support a wide variety of functionality in the event no other method is suitable. Common uses include:
- Submitting form data to a server
- Posting a message to a bulletin board, newsgroup, mailing list, or blog
- Creating a new resource, to be assigned a URI by the server
- Appending an event to a log
- Purging a cache
- Conditionally deleting multiple resources at once
Writing requests (clients)
Clients may submit POST requests when indicated by the server.
In HTML, this is indicated with a <form method="post">
element.
This can also be indicated by certain link relationships, whose relation definition includes some POST semantics.
The media type of the resource can also imply what a POST will do. In Atom, a new member is added to a collection with a POST to the collection.
Reading requests (servers)
If the request results in the creation of a new resource, send 201 (Created).
If the client sent Prefer: respond-async, the server can choose to send a 202 (Accepted) response.
Usage in Web browsers
method="post"
is currently the only method supported by HTML in Web browsers that is non-safe and suitable for submitting data to a server. Support for other methods, as well as HTTP headers not supported by browsers, are typically tunneled through the body of a POST request.
Usage in collections
In AtomPub, POST is used for new resource creation. The server fully manages its URI namespace by deciding where to place the new item, so PUT is only used for editing existing resources. See AtomPub: Control and Publishing.
Idempotent usage
There is no standardized, reliable way to re-issue a POST request if the request failed.
As a general principle, servers should not allow two identical POST requests to be made: Some Web browsers may heuristically re-issue POST requests if they don't think the server received the request at all; or some users may accidentally double-click the Submit button. Servers may accept a "nonce" (number used once) or a timestamp field, to distinguish between otherwise identical messages.
For most cases where POST is used, a PUT request can offer the same functionality, by using a client-selected UUID with If-None-Match: *
. See Idempotent Requests for more information.
Safe usage
In cases where the method is safe (does not change the state of the server), the server can also consider accepting the REPORT or SEARCH methods, or using a query parameter in a GET request. For more information, see Queries in HTTP.
Overview table
- Name
- POST
- Description
- Sends the server a payload to be processed by the target resource.
- Safeness
- Unsafe
- Conditional fail
- 412 Precondition Failed
- Specification
- RFC 5789: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content ยง4.3.3. POST