Editing HTTP (section)

== HTTP/1.1 request messages{{anchor|Request_message}} ==
Request messages are sent by a client to a target server.{{refn|group=note|name=http-23-message|HTTP/2 and HTTP/3 have a different representation for HTTP methods and headers.}}

=== Request syntax ===
A client sends ''request messages'' to the server, which consist of:<ref name="rfc9112-2.1">{{cite IETF |rfc=9112 |sectionname=Message format |section=2.1 |title=RFC 9112: HTTP/1.1}}</ref>

* a '''request line''', consisting of the case-sensitive request method, a [[Space (punctuation)|space]], the requested URI, another space, the protocol version, a [[carriage return]], and a [[line feed]], e.g.:
{{sxhl|2=http|1=GET /images/logo.png HTTP/1.1}}
* zero or more [[HTTP request header field|request header fields]] (at least 1 or more headers in case of HTTP/1.1), each consisting of the case-insensitive field name, a colon, optional leading [[Whitespace (computer science)|whitespace]], the field value, an optional trailing whitespace and ending with a carriage return and a line feed, e.g.:
 Host: www.example.com
 Accept-Language: en
* an empty line, consisting of a carriage return and a line feed;
* an optional [[HTTP message body|message body]].

In the HTTP/1.1 protocol, all header fields except <code>Host: hostname</code> are optional.

A request line containing only the path name is accepted by servers to maintain compatibility with HTTP clients before the HTTP/1.0 specification in {{IETF RFC|1945}}.<ref name="apacheweek_com-http11">{{cite web |title=Apache Week. HTTP/1.1 |url=https://www.apacheweek.com/features/http11 |access-date=2021-05-03 |archive-date=2021-06-02 |archive-url=https://web.archive.org/web/20210602213136/http://www.apacheweek.com/features/http11 |url-status=dead }} 090502 apacheweek.com</ref>

=== Request methods ===
[[File:Http request telnet ubuntu.png|thumb|right|An HTTP/1.1 request made using telnet. The [[HTTP request|request]] message, [[HTTP response|response]] header section, and response body are highlighted.]]
HTTP defines methods (sometimes referred to as ''verbs'', but nowhere in the specification does it mention ''verb'') to indicate the desired action to be performed on the identified resource. What this resource represents, whether pre-existing data or data that is generated dynamically, depends on the implementation of the server. Often, the resource corresponds to a file or the output of an executable residing on the server. The HTTP/1.0 specification<ref name="rfc1945-8">{{cite IETF |rfc=1945 |title=Hypertext Transfer Protocol – HTTP/1.0 |first1=Tim |last1=Berners-Lee |first2=Roy T. |last2=Fielding |first3=Henrik Frystyk |last3=Nielsen |publisher=IETF |sectionname=Method Definitions |section=8 |pages=30–32}}</ref> defined the GET, HEAD, and POST methods as well as listing the PUT, DELETE, LINK and UNLINK methods under additional methods.  However, the HTTP/1.1 specification<ref name="rfc2616-9">{{cite IETF |rfc=2616 |sectionname=Method Definitions |section=9 |title=RFC 2616|pages=51–57}}</ref> formally defined and added five new methods: PUT, DELETE, CONNECT, OPTIONS, and TRACE. Any client can use any method and the server can be configured to support any combination of methods. If a method is unknown to an intermediate, it will be treated as an unsafe and [[idempotence|non-idempotent]] method. There is no limit to the number of methods that can be defined, which allows for future methods to be specified without breaking existing infrastructure. For example, [[WebDAV]] defined seven new methods and {{IETF RFC|5789}} specified the [[PATCH (HTTP)|PATCH]] method.

Method names are case sensitive.<ref name="rfc9112-3">{{cite IETF |rfc=9112 |section=3 |sectionname=Request Line |title=RFC 9112, HTTP/1.1}}</ref><ref name="rfc9110-9.1">{{cite IETF |rfc=9110 |section=9.1 |sectionname=Methods: Overview| title=RFC 9110, HTTP Semantics}}</ref> This is in contrast to HTTP header field names which are case-insensitive.<ref name="rfc9110-6.3">{{cite IETF |rfc=9110 |section=6.3 |sectionname=Header Fields |title=RFC 9110, HTTP Semantics}}</ref>

{{anchor|GET method}}
; GET: The GET method requests that the target resource transfer a representation of its state. GET requests should only [[Data retrieval|retrieve data]] and should have no other effect. (This is also true of some other HTTP methods.)<ref name="rfc9110" /> For retrieving resources without making changes, GET is preferred over POST, as they can be [[addressability|addressed]] through a [[URL]]. This enables bookmarking and sharing and makes GET responses eligible for [[browser cache|caching]], which can save bandwidth. The [[W3C]] has published guidance principles on this distinction, saying, "[[Web application]] design should be informed by the above principles, but also by the relevant limitations."<ref>{{cite web |last=Jacobs |first=Ian |title=URIs, Addressability, and the use of HTTP GET and POST |url=https://www.w3.org/2001/tag/doc/whenToUseGet.html#checklist |work=Technical Architecture Group finding |publisher=W3C |access-date=26 September 2010 |year=2004}}</ref> See [[#Safe methods|safe methods]] below.

{{anchor|HEAD method}}
; HEAD: The HEAD method requests that the target resource transfer a representation of its state, as for a GET request, but without the representation data enclosed in the response body. This is useful for retrieving the representation metadata in the response header, without having to transfer the entire representation. Uses include checking whether a page is available through the [[HTTP status code|status code]] and quickly finding the size of a [[computer file|file]] (<code>Content-Length</code>).

{{anchor|POST method}}
; POST: The [[POST (HTTP)|POST method]] requests that the target resource process the representation enclosed in the request according to the semantics of the target resource. For example, it is used for posting a message to an [[Internet forum]], subscribing to a [[mailing list]], or completing an [[online shopping]] transaction.<ref name="rfc9110-9.3.3">{{cite IETF |rfc=9110 |sectionname=POST |section=9.3.3 |title=RFC 9110, HTTP Semantics}}</ref>

{{anchor|PUT method}}
; PUT: The PUT method requests that the target resource create or update its state with the state defined by the representation enclosed in the request. A distinction from POST is that the client specifies the target location on the server.<ref name="rfc9110-9.3.4">{{cite IETF |rfc=9110 |sectionname=PUT |section=9.3.4 |title=RFC 9110, HTTP Semantics}}</ref>

{{anchor|DELETE method}}
; DELETE: The DELETE method requests that the target resource delete its state.

{{anchor|CONNECT method}}
; CONNECT: The CONNECT method requests that the intermediary establish a [[tunneling protocol|TCP/IP tunnel]] to the origin server identified by the request target. It is often used to secure connections through one or more [[HTTP proxy|HTTP proxies]] with [[Transport Layer Security|TLS]].<ref name="rfc9110-9.3.6">{{cite IETF |rfc=9110 |sectionname=CONNECT |section=9.3.6 |title=RFC 9110, HTTP Semantics}}</ref><ref name="HTTP-proxy-arbitrary-TCP">{{cite web |url=https://www.kb.cert.org/vuls/id/150227 |title=Vulnerability Note VU#150227: HTTP proxy default configurations allow arbitrary TCP connections |access-date=2007-05-10 |date=2002-05-17 |publisher=[[CERT Coordination Center|US-CERT]]}}</ref> See [[HTTP tunnel#HTTP CONNECT method|HTTP CONNECT method]].

{{anchor|OPTIONS method}}
; OPTIONS: The OPTIONS method requests that the target resource transfer the HTTP methods that it supports. This can be used to check the functionality of a web server by requesting '*' instead of a specific resource.

{{anchor|TRACE method}}
; TRACE: The TRACE method requests that the target resource transfer the received request in the response body. That way a client can see what (if any) changes or additions have been made by intermediaries.

{{anchor|PATCH method}}
; PATCH: The [[PATCH (HTTP)|PATCH method]] requests that the target resource modify its state according to the partial update defined in the representation enclosed in the request. This can save bandwidth by updating a part of a file or document without having to transfer it entirely.<ref name="rfc5789">{{cite IETF |rfc=5789 |title=PATCH Method for HTTP |first1=Lisa |last1=Dusseault |first2=James M. |last2=Snell |date=March 2010 |publisher=IETF}}</ref>

All general-purpose web servers are required to implement at least the GET and HEAD methods, and all other methods are considered optional by the specification.<ref name="rfc9110-9.1" />

{{anchor|Properties of request methods table}}
{| class="wikitable sortable" style="text-align: center; width: auto; table-layout: fixed;"
|+Properties of request methods
|-
!scope="col"| Request method
!scope="col"| RFC
!scope="col"| Request has payload body
!scope="col"| Response has payload body
!scope="col"| Safe
!scope="col"| Idempotent
!scope="col"| Cacheable
|-
!scope="row"| GET
| {{IETF RFC|9110}}
| {{Optional}}
| {{Yes}}
| {{Yes}}
| {{Yes}}
| {{Yes}}
|-
!scope="row"| HEAD
| {{IETF RFC|9110}}
| {{Optional}}
| {{No}}
| {{Yes}}
| {{Yes}}
| {{Yes}}
|-
!scope="row"| POST
| {{IETF RFC|9110}}
| {{Yes}}
| {{Yes}}
| {{No}}
| {{No}}
| {{Yes}}
|-
!scope="row"| PUT
| {{IETF RFC|9110}}
| {{Yes}}
| {{Yes}}
| {{No}}
| {{Yes}}
| {{No}}
|-
!scope="row"| DELETE
| {{IETF RFC|9110}}
| {{Optional}}
| {{Yes}}
| {{No}}
| {{Yes}}
| {{No}}
|-
!scope="row"| CONNECT
| {{IETF RFC|9110}}
| {{Optional}}
| {{Yes}}
| {{No}}
| {{No}}
| {{No}}
|-
!scope="row"| OPTIONS
| {{IETF RFC|9110}}
| {{Optional}}
| {{Yes}}
| {{Yes}}
| {{Yes}}
| {{No}}
|-
!scope="row"| TRACE
| {{IETF RFC|9110}}
| {{No}}
| {{Yes}}
| {{Yes}}
| {{Yes}}
| {{No}}
|-
!scope="row"| PATCH
| {{IETF RFC|5789}}
| {{Yes}}
| {{Yes}}
| {{No}}
| {{No}}
| {{No}}
|}

==== Safe methods ====
A request method is ''safe'' if a request with that method has no intended effect on the server. The methods GET, HEAD, OPTIONS, and TRACE are defined as safe. In other words, safe methods are intended to be [[Command–query separation|read-only]]. Safe methods can still have [[Side effect (computer science)|side effects]] not seen by the client, such as appending request information to a [[Server log|log file]] or charging an [[Web banner|advertising account]].

In contrast, the methods POST, PUT, DELETE, CONNECT, and PATCH are not safe. They may modify the state of the server or have other effects such as sending an [[email]]. Such methods are therefore not usually used by conforming [[Internet bot|web robots]] or web crawlers; some that do not conform tend to make requests without regard to context or consequences.

Despite the prescribed safety of GET requests, in practice their handling by the server is not technically limited in any way. Careless or deliberately irregular programming can allow GET requests to cause non-trivial changes on the server. This is discouraged because of the problems which can occur when [[web caching]], [[search engines]], and other automated agents make unintended changes on the server. For example, a website might allow deletion of a resource through a URL such as ''<nowiki>https://example.com/article/1234/delete</nowiki>'', which, if arbitrarily fetched, even using GET, would simply delete the article.<ref name="oreilly-get-rails">{{cite book |last=Ediger |first=Brad |date=2007-12-21 |title=Advanced Rails: Building Industrial-Strength Web Apps in Record Time |url=https://shop.oreilly.com/product/9780596510329.do |publisher=O'Reilly Media, Inc. |page=188 |isbn= 978-0596519728 |quote=A common mistake is to use GET for an action that updates a resource. [...] This problem came into the Rails public eye in 2005, when the Google Web Accelerator was released.}}</ref> A properly coded website would require a DELETE or POST method for this action, which non-malicious bots would not make.

One example of this occurring in practice was during the short-lived [[Google Web Accelerator]] beta, which prefetched arbitrary URLs on the page a user was viewing, causing records to be automatically altered or deleted ''en masse''. The [[Beta test|beta]] was suspended only weeks after its first release, following widespread criticism.<ref>{{cite web |url=https://blogs.adobe.com/cantrell/archives/2005/06/what_have_we_le.html |title=What Have We Learned From the Google Web Accelerator? |last=Cantrell |first=Christian |archive-url=https://web.archive.org/web/20170819161233/https://blogs.adobe.com/cantrell/archives/2005/06/what_have_we_le.html |archive-date=2017-08-19 |date=2005-06-01 |website=Adobe Blogs |publisher=Adobe |access-date=2018-11-19 |url-status=dead }}</ref><ref name="oreilly-get-rails" />

==== Idempotent methods ====
{{see also|Idempotence#Computer science meaning}}
A request method is ''idempotent'' if multiple identical requests with that method have the same effect as a single such request. The methods PUT and DELETE, and safe methods are defined as idempotent. Safe methods are trivially idempotent, since they are intended to have no effect on the server whatsoever; the PUT and DELETE methods, meanwhile, are idempotent since successive identical requests will be ignored. A website might, for instance, set up a PUT endpoint to modify a user's recorded email address. If this endpoint is configured correctly, any requests which ask to change a user's email address to the same email address which is already recorded—e.g. duplicate requests following a successful request—will have no effect. Similarly, a request to DELETE a certain user will have no effect if that user has already been deleted.

In contrast, the methods POST, CONNECT, and PATCH are not necessarily idempotent, and therefore sending an identical POST request multiple times may further modify the state of the server or have further effects, such as sending multiple [[email]]s. In some cases this is the desired effect, but in other cases it may occur accidentally. A user might, for example, inadvertently send multiple POST requests by clicking a button again if they were not given clear feedback that the first click was being processed. While [[web browser]]s may show [[alert dialog box]]es to warn users in some cases where reloading a page may re-submit a POST request, it is generally up to the web application to handle cases where a POST request should not be submitted more than once.

Note that whether or not a method is idempotent is not enforced by the protocol or web server. It is perfectly possible to write a web application in which (for example) a database insert or other non-idempotent action is triggered by a GET or other request. To do so against recommendations, however, may result in undesirable consequences, if a [[user agent]] assumes that repeating the same request is safe when it is not.

==== Cacheable methods ====
{{see also|Web cache}}
A request method is ''cacheable'' if responses to requests with that method may be stored for future reuse. The methods GET, HEAD, and POST are defined as cacheable.

In contrast, the methods PUT, DELETE, CONNECT, OPTIONS, TRACE, and PATCH are not cacheable.

=== Request header fields ===
{{see also|List of HTTP header fields#Request fields}}
Request header fields allow the client to pass additional information beyond the request line, acting as request modifiers (similarly to the parameters of a procedure). They give information about the client, about the target resource, or about the expected handling of the request.