POST

The HTTP POST method is a type of HTTP request that is used to send data to a server and is typically utilized for interacting with a specific resource.

Table of Contents

Usage

A HTTP request of this type is intended to send data to the server, where it will make changes through either the creation of a resource or the interaction with one. The representation of the message body is indicated by the Content-Type header. Depending on this value, the server has different expectations as to how the message body is formatted.

  • application/x-www-form-urlencoded

    This is the default Content-Type, which specifies encoding in key-value pairs. Each pair is delimited by the ampersand “&” character, and assignments are indicated by the equals sign “=”. Non-alphanumeric values are escaped using percent-encoding. Multiple key/value pairs can be used on a single line.

  • multipart/form-data

    In a multipart form, each value is sent as a block of data and a delimiter is used to separate each part. The delimiter between parts is called the Boundary and it is specified as part of the Content-Type header. The keys are specified in the Content-Disposition header of each message body part.

  • text/plain

    There is no prescribed format for the message body and the server is expected to process it accordingly.

The HTTP status code returned by the server after receiving an HTTP POST request will vary depending on the result of the internal processing.

The HTTP POST method is similar to HTTP PUT, where it can be used to create a resource, although PUT is idempotent whereas an identical POST request is not.

A HTTP POST request may be cacheable but only if information about the freshness is included.

Common uses of HTTP POST requests are:

  • Sending a block of data to a data processing resource, such as the pieces of information entered by a user on an HTML form.

  • Altering or adding data to an existing resource.

  • Transferring a message or blog article to be posted on a forum. If the server intends the client to cache the result so that it can be retrieved through a subsequent HTTP GET, it might return a 200 OK status code with a Content-Location header that matches the HTTP request from the client.

  • Instructing the server to perform actions such as starting or stopping tasks.

  • Creating a novel resource. If the HTTP request succeeds then a 201 Created status code is an appropriate response.

Example: application/x-www-form-urlencoded

In this example, the client sends a HTTP request to the server to assign two values. The “Job” key is assigned the value 100 and the key “Priority” is assigned a value of 2. The server acknowledges the HTTP request and continues to process it.

Request

POST / HTTP/1.1
Host: www.example.re
Content-Type: application/x-www-form-urlencoded
Content-Length: 18

Job=100&Priority=2

Response

HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 137

<html>
  <head>
    <title>Job Started</title>
  </head>
  <body>
    <p>Job #100 has been started with priority 2.</p>
  </body>
</html>

Example: multipart/form-data

In this example, the client sends the same HTTP request as in the previous example but with the data in the multipart format, delimited by “NextField” as the boundary. The server responds with the 202 Accepted HTTP status code to inform the client that the HTTP request has been accepted for processing.

Request

POST / HTTP/1.1
Host: www.example.re
Content-Type: multipart/form-data; boundary=”NextField”
Content-Length: 125

--NextField
Content-Disposition: form-data; name=”Job”

100

-- NextField
Content-Disposition: form-data; name=”Priority”

2

Response

HTTP/1.1 202 Accepted
Content-Length: 0

Example: text/plain

In this example, the client sends data in plain text format. The intention is to create a new resource on the server, and it responds with HTTP status code 201 Created to say that it was done successfully.

Request

POST /help.txt HTTP/1.1
Host: www.example.re
Content-Type: text/plain
Content-Length: 51

Please visit www.example.re for the latest updates!

Response

HTTP/1.1 201 Created
Content-Type: text/plain
Content-Length: 26

File created successfully.

Takeaway

The HTTP POST request method is used to send a block of data to the server. It is neither safe nor idempotent but may be cacheable. The HTTP request message body and resulting HTTP status code will vary depending on the type of data the server expects and the type of processing that it does.

Last updated: August 2, 2023