Search Results
  1. HTTP (Hypertext Transfer Protocol)
  1. HTTP Methods
  1. POST
    1. Writing requests (clients)
    2. Reading requests (servers)
    3. Usage in Web browsers
    4. Usage in collections
    5. Idempotent usage
    6. Safe usage
    7. Overview table

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