HTTP POST

The HTTP POST method is used to create or add a resource on the server. Typically, the POST request adds a new resource to the server, while the PUT request replaces an existing resource on the server. Unlike GET and HEAD requests, the HTTP POST requests may change the server state.

You can send data to the server in the body of the POST message. The type and size of data are not limited. But you must specify the data type in the Content-Type header and the data size in the Content-Length header fields. The HTTP POST requests can also send data to the server using the URL parameters. In this case, you are limited to the maximum size of the URL, which is about 2000 characters (it depends on the browser).

The HTTP POST method is not idempotent, which means that sending an identical POST request multiple times may additionally affect the state or cause further side effects (eg. on financial transactions).

HTTP POST Example

The following HTTP POST request example demonstrates sending a POST request to the server. In this example, the 'Content-Type: application/json' request header indicates the media type of the resource, and the 'Content-Length: 85' request header indicates the size of the data in the request body.

HTTP POST Request Example Run Example

POST /echo/post/json HTTP/1.1
Authorization: Bearer mt0dgHmLJMVQhvjpNXDyA83vA_PxH23Y
Accept: application/json
Content-Type: application/json
Content-Length: 85
Host: reqbin.com

{
"Id": 12345,
"Customer": "John Smith",
"Quantity": 1,
"Price": 10.00
}

And the server response:

Server Response to HTTP POST Request

HTTP/1.1 200 OK
Content-Length: 19
Content-Type: application/json

{"success":"true"}

Some notes on HTTP POST requests:

POST requests are never cached
POST requests do not remain in the browser history
POST requests cannot be bookmarked

HTTP GET vs POST

	GET	POST
Browser BACK button/Reload	Harmless	Data will be re-submitted (the browser should alert the user that the data are about to be re-submitted)
Bookmarked	Can be bookmarked	Cannot be bookmarked
Cached	Can be cached	Not cached
History	Parameters remain in browser history	Parameters are not saved in browser history
Restrictions on data length	Yes, when sending data, the GET method adds the data to the URL; and the length of a URL is limited (maximum URL length is 2048 characters)	No restrictions
Restrictions on data type	Only ASCII characters allowed	No restrictions. Binary data is also allowed
Security	GET is less secure compared to HTTP POST because data sent is part of the URL. Never use GET when sending passwords or other sensitive information!
Visibility	Data is visible to everyone in the URL	Data is not displayed in the URL

HTTP PUT vs POST

The fundamental difference between the HTTP POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. In contrast; the URI in a PUT request identifies the entity enclosed with the request. Practically speaking, POST is used to append a resource to an existing collection, while PUT is used to update an existing resource.

http-method http-request post-request post-example request-example