ContextQMD
Back to Content

PUT request method

files/en-us/web/http/reference/methods/put/index.md

latest3.1 KB
Original Source

The PUT HTTP method creates a new resource or replaces a representation of the target resource with the request {{Glossary("HTTP Content", "content")}}.

The difference between PUT and {{HTTPMethod("POST")}} is that PUT is {{Glossary("idempotent")}}: calling it once is no different from calling it several times successively (there are no side effects).

<table class="properties"> <tbody> <tr> <th scope="row">Request has body</th> <td>Yes</td> </tr> <tr> <th scope="row">Successful response has body</th> <td>May</td> </tr> <tr> <th scope="row">{{Glossary("Safe/HTTP", "Safe")}}</th> <td>No</td> </tr> <tr> <th scope="row">{{Glossary("Idempotent")}}</th> <td>Yes</td> </tr> <tr> <th scope="row">{{Glossary("Cacheable")}}</th> <td>No</td> </tr> <tr> <th scope="row"> Allowed in <a href="/en-US/docs/Learn_web_development/Extensions/Forms">HTML forms</a> </th> <td>No</td> </tr> </tbody> </table>

Syntax

http
PUT <request-target>["?"<query>] HTTP/1.1
  • <request-target>
    • : Identifies the target resource of the request when combined with the information provided in the {{HTTPHeader("Host")}} header. This is an absolute path (e.g., /path/to/file.html) in requests to an origin server, and an absolute URL in requests to proxies (e.g., http://www.example.com/path/to/file.html).
  • <query> {{optional_inline}}
    • : An optional query component preceded by a question-mark ?. Often used to carry identifying information in the form of key=value pairs.

Examples

Successfully creating a resource

The following PUT request asks to create a resource at example.com/new.html with the content <p>New File</p>:

http
PUT /new.html HTTP/1.1
Host: example.com
Content-type: text/html
Content-length: 16

<p>New File</p>

If the target resource does not have a current representation and the PUT request successfully creates one, then the origin server must send a {{HTTPStatus("201", "201 Created")}} response:

http
HTTP/1.1 201 Created
Content-Location: /new.html

If the target resource does have a current representation and that representation is successfully modified with the state in the request, the origin server must send either a {{HTTPStatus("200", "200 OK")}} or a {{HTTPStatus("204", "204 No Content")}} to indicate successful completion of the request:

http
HTTP/1.1 204 No Content
Content-Location: /existing.html

Specifications

{{Specifications}}

Browser compatibility

The browser doesn't use the PUT method for user-initiated actions, so "browser compatibility" doesn't apply. Developers can set this request method using fetch().

See also