HTTP Request: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(33 intermediate revisions by the same user not shown)
Line 17: Line 17:
</pre>
</pre>


The first line of the request specifies the ''[[#The_HTTP_Method|method]]'', the  [[#Request-URI|Request-URI]] of the document and the version of the HTML protocol it is using.  
The first line of the request specifies the ''[[#The_HTTP_Method|method]]'', the  [[#Request-URI|Request-URI]] of the document and the version of the HTML protocol it is using. The next lines contain optional [[#Headers|Headers]]. After the headers, the client sends a [[#The_Blank_Line|blank line]] to indicate the end of the header section. An optional body follows.


The next lines contain optional ''header information'', that carry extra information about the request. After the headers, the client sends a ''blank line'' to indicate the end of the header section.
=The HTTP Method=


=The HTTP Method=
The '''HTTP method''' is the client's way of telling the server what it wants to do to a [[REST and Hypermedia#Resource|resource]]. The '''HTTP method''' is also known as '''HTTP verb'''.


The HTTP Methods are: GET, POST, PUT, HEAD, DELETE, TRACE, OPTIONS and CONNECT. The most common are GET and POST.
The HTTP Methods are: GET, POST, PUT, HEAD, DELETE, TRACE, OPTIONS and CONNECT. The most common are GET and POST.
Line 31: Line 31:
The GET method is designed for getting information, such as a document, a chart or the result from a database query. The GET method can include as part of the request some of its own information that better describes what to get. This information is passed as a ''query string'': a sequence of characters appended to the request URL. Placing the extra information in the URL in this way allows the page to be bookmarked or emailed like any other. Because GET requests theoretically shouldn't need to send large amounts of information, some servers limit the length of URL's and query string to about 240 characters.
The GET method is designed for getting information, such as a document, a chart or the result from a database query. The GET method can include as part of the request some of its own information that better describes what to get. This information is passed as a ''query string'': a sequence of characters appended to the request URL. Placing the extra information in the URL in this way allows the page to be bookmarked or emailed like any other. Because GET requests theoretically shouldn't need to send large amounts of information, some servers limit the length of URL's and query string to about 240 characters.


GET is read-only. It is ''idempotent'' (repeated application does not modify the resource except the first time) and ''safe'' (does not change the state of the resource).  
GET is read-only. It is '''idempotent''' (repeated application does not modify the resource except the first time) and ''safe'' (does not change the state of the resource).
 
Also see: {{Internal|REST_and_Hypermedia#GET|HTTP GET Semantics for REST Applications}}


==<tt>POST</tt>==
==<tt>POST</tt>==
Line 42: Line 44:
* <tt>multipart/form-data</tt>
* <tt>multipart/form-data</tt>


POST is ''non-idempotent'' and ''unsafe'' operation, each POST method is allowed to modify the resource in an unique way. Information may or may not be sent information with the requests. Information may or may not be received with the response.
POST is '''non-idempotent''' and '''unsafe''' operation, each POST method is allowed to modify the resource in an unique way. Information may or may not be sent information with the requests. Information may or may not be received with the response.
 
Also see: {{Internal|REST_and_Hypermedia#POST|HTTP POST Semantics for REST Applications}}


==<tt>PUT</tt>==
==<tt>PUT</tt>==


The PUT request instructs the server to store the message body sent with the request under the location provided in the HTTP message. Usually modeled as an insert or update. It is ''idempotent''.  
The PUT request instructs the server to store the message body sent with the request under the location provided in the HTTP message. Usually modeled as an insert or update. It is '''idempotent'''.
 
Also see: {{Internal|REST_and_Hypermedia#PUT|HTTP PUT Semantics for REST Applications}}


==<tt>DELETE</tt>==
==<tt>DELETE</tt>==


The DELETE request is used to remove resources. It is ''idempotent''.
The DELETE request is used to remove resources. It is ''idempotent''.
Also see: {{Internal|REST_and_Hypermedia#DELETE|HTTP DELETE Semantics for REST Applications}}


==<tt>HEAD</tt>==
==<tt>HEAD</tt>==


Similar to GET, except that instead of returning a response body, it only returns a response code and headers.
Similar to GET, except that instead of returning a response body, it only returns a response code and headers.
Also see: {{Internal|REST_and_Hypermedia#HEAD|HTTP HEAD Semantics for REST Applications}}


==<tt>OPTIONS</tt>==
==<tt>OPTIONS</tt>==


Used to request information about communication options of the resource. Allows the client to determine the capabilities of the server, without triggering any resource action or retrieval.
Used to request information about communication options of the resource. Allows the client to determine the capabilities of the server, without triggering any resource action or retrieval.
Also see: {{Internal|REST_and_Hypermedia#OPTIONS|HTTP OPTIONS Semantics for REST Applications}}
==<tt>PATCH</tt>==
{{External|https://datatracker.ietf.org/doc/html/rfc5789}}
HTTP PATCH extends HTTP with a method to perform partial modifications to resources. It can be used with application/json-patch+json media type, for example, to apply [[JSON Patch]]es.
{{Internal|REST_and_Hypermedia#PATCH|HTTP PATCH Semantics for REST Applications}}
=Path=
<font color=darkgray>Reconcile Path and Request-URI (below)</font>
==<span id='Path_Parameter'></span>Path Parameters==
{{Internal|REST_and_Hypermedia#Path_Parameter|REST Path Parameter}}
==<span id='Query_Parameter'></span>Query Parameters==
{{Internal|REST_and_Hypermedia#Query_Parameter|REST Query Parameter}}


=Request-URI=
=Request-URI=
Line 64: Line 92:
The Request-URI is a Uniform Resource Identifier and identifies the resource upon which to apply the request.
The Request-URI is a Uniform Resource Identifier and identifies the resource upon which to apply the request.


=HTTP Query String Parameters=
==HTTP Query String Parameters==


HTTP query string parameters are encoded in the URL and can be accessed from a servlet using: <tt>HttpServletRequest.getParameter(String name)</tt>
HTTP query string parameters are encoded in the URL and can be accessed from a servlet using: <tt>HttpServletRequest.getParameter(String name)</tt>
Line 76: Line 104:
"a" and "b" are query string parameters.
"a" and "b" are query string parameters.


=HTTP Method Parameters=
==HTTP Method Parameters==
<font color=red>
 
'''TODO'''
=Headers=
</font>
 
{{External|RFC 822}}


=The Blank Line=
The HTTP request headers are present in the HTTP request itself, as a list of strings, terminated by an empty line. The header section can be (or not) followed by a [[#The_HTTP_Request_Body|body]].
 
The header format is governed by RFC822. From RFC822: Each header field can be viewed as a single, logical  line  of ASCII  characters,  comprising  a field-name, followed by a colon (":") and a field-body. For convenience, the field-body  portion  of  this  conceptual entity  can be split into a multiple-line representation (folding). The field name must be composed of printable ASCII characters (i.e., characters that  have  values  between  33 and 126, except colon).
 
The field value can be preceded or trailed by any amount of white space, though a simple space character is preferred. The white space occurring before the first non-whitespace character of the field body or after the last non-whitespace character of the field body may be removed without changing the semantics of the field body. The field body can contain quoted strings.
 
Header fields can be extended over multiple lines by preceding each extra line with at least one space or tab.
 
The field body can be empty: the name-only headers are legal.
 
<font color=red>The field body may contain white spaces. In this case, the white space may be replaced with a single space character before interpreting the field value or forwarding the message</font>
 
HTTP request headers can be accessed from an Apache httpclient method using <tt>HttpMethod.getRequestHeaders()</tt>. HTTP request headers can be accessed from a servlet request using <tt>HttpServletRequest.getHeader(String name)</tt>.


=The HTTP Request Body=
{{Internal|REST_and_Hypermedia#Request_Header|REST Request Header}}


<font color=red>The request may transfer an entity. An entity consists of entity-header fields and an entity-body.</font>
==Duplicate Header Names==


The HTTP protocol requires that requests which include a body either use chunked transfer encoding or send a Content-Length request header.
Multiple headers with the same field name may be present in a message. In this case, the entire value for that header is defined as a comma-separated list, where the value is the combination of the multiple header fields into one "field-name: field-value" pair, without changing the semantics of the message, by appending each subsequent field-value to the first, each separated by a comma. The order in which header fields with the same field-name are received is therefore significant to the interpretation of the combined field value. A proxy must not change this order when a message is forwarded.


==HTTP Entity Header Fields==
==Header Case Independence==


===Allow===
When working with header names, capitalization does not matter. Case is to be ignored. For  example, the field-names "From", "FROM", "from", and even "FroM" are semantically equal and should all be treated identically.


===Content-Encoding===
==Header Order==


===Content-Language===
The order in which header fields with differing field names are received is not significant. However, it is "good practice" to send general header fields first, followed by request header or response header fields, and ending with the entity header fields.


===Content-Length===
==General Headers==


===Content-Location===
{{Internal|General_HTTP_Header_Fields|General Headers}}


===Content-MD5===
==Request Headers==


===Content-Range===
* [[HTTP Request Header Accept|Accept]]
* [[HTTP Request Header Accept-Charset|Accept-Charset]]
* [[HTTP Request Header Accept-Encoding|Accept-Encoding]]
* [[HTTP Request Header Accept-Language|Accept-Language]]
* [[HTTP Request Header Authorization|Authorization]]
* [[HTTP Request Header Expect|Expect]]
* [[HTTP Request Header From|From]]
* [[HTTP Request Header Host|Host]]
* [[HTTP Request Header If-Match|If-Match]]
* [[HTTP Request Header If-Modified-Since|If-Modified-Since]]
* [[HTTP Request Header If-None-Match|If-None-Match]]
* [[HTTP Request Header If-Range|If-Range]]
* [[HTTP Request Header If-Unmodified-Since|If-Unmodified-Since]]
* [[HTTP Request Header Max-Forwards|Max-Forwards]]
* [[HTTP Request Header Proxy-Authorization|Proxy-Authorization]]
* [[HTTP Request Header Range|Range]]
* [[HTTP Request Header Referer|Referer]]
* [[HTTP Request Header TE|TE]]
* [[HTTP Request Header User-Agent|User-Agent]]


===Content-Type===
==Entity Headers==


===Expires===
{{Internal|Entity_HTTP_Header_Fields|Entity Headers}}


===Last-Modified===
=The Blank Line=


==HTTP Request Entity Body==
=The HTTP Request Body=


<font color=red>
The optional request body is referred to as the ''HTTP entity'' or payload.


The entity-body (if any) sent with the HTTP request or response is in a format and encoding defined by the [[#HTTP_Entity_Header_Fields|entity-header fields]].
{{Internal|HTTP Entity|HTTP Entity}}


</font>
Also see: {{Internal|REST_and_Hypermedia#Request_Body|REST Request Body}}

Latest revision as of 18:40, 29 July 2021

Internal

Overview

A HTTP request consists of a header section, followed by a blank line, followed by the request body.

An example of a header section follows:

GET /intro.html HTTP/1.1
User-Agent: Mozilla/4.0
Accept: image/gif, image/jpeg, text/*, */*

The first line of the request specifies the method, the Request-URI of the document and the version of the HTML protocol it is using. The next lines contain optional Headers. After the headers, the client sends a blank line to indicate the end of the header section. An optional body follows.

The HTTP Method

The HTTP method is the client's way of telling the server what it wants to do to a resource. The HTTP method is also known as HTTP verb.

The HTTP Methods are: GET, POST, PUT, HEAD, DELETE, TRACE, OPTIONS and CONNECT. The most common are GET and POST.

HTTP methods in RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

GET

The GET method is designed for getting information, such as a document, a chart or the result from a database query. The GET method can include as part of the request some of its own information that better describes what to get. This information is passed as a query string: a sequence of characters appended to the request URL. Placing the extra information in the URL in this way allows the page to be bookmarked or emailed like any other. Because GET requests theoretically shouldn't need to send large amounts of information, some servers limit the length of URL's and query string to about 240 characters.

GET is read-only. It is idempotent (repeated application does not modify the resource except the first time) and safe (does not change the state of the resource).

Also see:

HTTP GET Semantics for REST Applications

POST

The POST method is designed for posting information. A POST request passes all its data, of unlimited length, directly over the socket connection as part of its HTTP request body. The exchange is invisible to the client, the URL doesn't change at all, so POST requests cannot be bookmarked.

The data can be actually encoded over the connection using different encoding types:

  • application/x-www-form-urlencoded - this is what HttpClient uses by default.
  • multipart/form-data

POST is non-idempotent and unsafe operation, each POST method is allowed to modify the resource in an unique way. Information may or may not be sent information with the requests. Information may or may not be received with the response.

Also see:

HTTP POST Semantics for REST Applications

PUT

The PUT request instructs the server to store the message body sent with the request under the location provided in the HTTP message. Usually modeled as an insert or update. It is idempotent.

Also see:

HTTP PUT Semantics for REST Applications

DELETE

The DELETE request is used to remove resources. It is idempotent.

Also see:

HTTP DELETE Semantics for REST Applications

HEAD

Similar to GET, except that instead of returning a response body, it only returns a response code and headers.

Also see:

HTTP HEAD Semantics for REST Applications

OPTIONS

Used to request information about communication options of the resource. Allows the client to determine the capabilities of the server, without triggering any resource action or retrieval.

Also see:

HTTP OPTIONS Semantics for REST Applications

PATCH

https://datatracker.ietf.org/doc/html/rfc5789

HTTP PATCH extends HTTP with a method to perform partial modifications to resources. It can be used with application/json-patch+json media type, for example, to apply JSON Patches.

HTTP PATCH Semantics for REST Applications

Path

Reconcile Path and Request-URI (below)

Path Parameters

REST Path Parameter

Query Parameters

REST Query Parameter

Request-URI

The Request-URI is a Uniform Resource Identifier and identifies the resource upon which to apply the request.

HTTP Query String Parameters

HTTP query string parameters are encoded in the URL and can be accessed from a servlet using: HttpServletRequest.getParameter(String name)

Example:

http://localhost/something?a=100&b=200

"a" and "b" are query string parameters.

HTTP Method Parameters

Headers

RFC 822

The HTTP request headers are present in the HTTP request itself, as a list of strings, terminated by an empty line. The header section can be (or not) followed by a body.

The header format is governed by RFC822. From RFC822: Each header field can be viewed as a single, logical line of ASCII characters, comprising a field-name, followed by a colon (":") and a field-body. For convenience, the field-body portion of this conceptual entity can be split into a multiple-line representation (folding). The field name must be composed of printable ASCII characters (i.e., characters that have values between 33 and 126, except colon).

The field value can be preceded or trailed by any amount of white space, though a simple space character is preferred. The white space occurring before the first non-whitespace character of the field body or after the last non-whitespace character of the field body may be removed without changing the semantics of the field body. The field body can contain quoted strings.

Header fields can be extended over multiple lines by preceding each extra line with at least one space or tab.

The field body can be empty: the name-only headers are legal.

The field body may contain white spaces. In this case, the white space may be replaced with a single space character before interpreting the field value or forwarding the message

HTTP request headers can be accessed from an Apache httpclient method using HttpMethod.getRequestHeaders(). HTTP request headers can be accessed from a servlet request using HttpServletRequest.getHeader(String name).

REST Request Header

Duplicate Header Names

Multiple headers with the same field name may be present in a message. In this case, the entire value for that header is defined as a comma-separated list, where the value is the combination of the multiple header fields into one "field-name: field-value" pair, without changing the semantics of the message, by appending each subsequent field-value to the first, each separated by a comma. The order in which header fields with the same field-name are received is therefore significant to the interpretation of the combined field value. A proxy must not change this order when a message is forwarded.

Header Case Independence

When working with header names, capitalization does not matter. Case is to be ignored. For example, the field-names "From", "FROM", "from", and even "FroM" are semantically equal and should all be treated identically.

Header Order

The order in which header fields with differing field names are received is not significant. However, it is "good practice" to send general header fields first, followed by request header or response header fields, and ending with the entity header fields.

General Headers

General Headers

Request Headers

Entity Headers

Entity Headers

The Blank Line

The HTTP Request Body

The optional request body is referred to as the HTTP entity or payload.

HTTP Entity

Also see:

REST Request Body