The HTTP PUT request method is used to create a new resource or replace a representation of the target resource with the request payload¹. The request payload is the data that is sent to the server in the body of the request².

The difference between PUT and POST is that PUT is idempotent: calling it once or several times successively has the same effect (that is no side effect), whereas successive identical POST requests may have additional effects, akin to placing an order several times¹.

The syntax of a PUT request is:

The request-line consists of the method (PUT), the target resource (a URI), and the HTTP version. The Host header is mandatory, and specifies the host name and port number of the server. The Content-Type header indicates the media type of the request body. The Content-Length header indicates the size of the request body in bytes. The request body contains the representation of the resource to be created or updated¹.

An example of a PUT request is:

This request creates or replaces a resource named new.html on the server example.com with the content <p>New File</p>.

The response to a PUT request depends on whether the target resource already exists or not, and whether it is successfully modified or created. If the target resource does not have a current representation and the PUT request successfully creates one, then the server must inform the client by sending a 201 (Created) response. If the target resource does have a current representation and that representation is successfully modified in accordance with the state of the enclosed representation, then the server must send either a 200 (OK) or a 204 (No Content) response to indicate successful completion of the request¹.

An example of a 201 response is:

This response indicates that a new resource named new.html has been created on the server, and its location is given by the Content-Location header.

An example of a 204 response is:

This response indicates that an existing resource named existing.html has been modified on the server, and its location is given by the Content-Location header.

Some characteristics of PUT requests are:

• PUT requests can have a body²

• PUT requests are not safe, meaning they can change the state of the server¹

• PUT requests are idempotent, meaning they have no side effects when repeated¹

• PUT requests are not cacheable, meaning they cannot be stored by intermediaries¹

• PUT requests are not allowed in HTML forms¹