PUT

The HTTP PUT method is a type of HTTP request that creates or replaces a resource on the server with one that is included in the message body.

Usage

A HTTP request of this type is sent to either create a new resource or replace an existing one. In either case, multiple calls with an identical HTTP request will leave the server in the same state, meaning that it is an idempotent HTTP request.

The server will verify that the specified representation is compatible with the constraints that the server has in place. If the representation is not consistent then the server will either reconfigure or transform it appropriately, or return an appropriate and explanatory error message.

For example, if the Content-Type HTTP header expected for the resource by the server is the same as that specified by the message body, then it might respond with 201 Created HTTP status code to indicate that a new resource has been added. In the case that one is being replaced, the 200 OK or 204 No Content HTTP status code responses are more appropriate. If instead, the Content-Type HTTP header field is not compatible and cannot be reconfigured or transformed by the server, the server will respond with the 415 Unsupported Media Type HTTP status code.

Another common error HTTP response status code to an HTTP PUT request is 409 Conflict, which informs that the server is unable to resolve resource conflicts that are not related to the Content-Type HTTP header.

Example

In this example, the client sends a block of text with the expectation that a new file will be created. The server sends the 201 Created HTTP status code to indicate that a new resource was indeed created.

Request

PUT /newfile.txt HTTP/1.1
Host: www.example.re
Content-Type: text/plain
Content-Length: 37

This is the contents of my text file.

Response

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

File created successfully.

Takeaway

The HTTP PUT request method is used to create or replace existing resources. Consistency checking is the responsibility of the server. This method is not safe or cacheable, but it is idempotent.