A request, as defined by RFC-7230 Section 3, is a text-based message, which includes the following required information at a minimum:
- Request method (RFC-7231 4.3; RFC-5789 2): The method is the action the client would like to perform on the resource. Enumerated HTTP methods are a finite list of verbs, and are outlined in the preceding two RFCs. The Go net/http package contains a list of constants for referencing the various methods, as can be seen in the documentation: https://golang.org/pkg/net/http/#pkg-constants.
-
Request target (RFC-7230 5.3): The request target, derived from the Uniform Resource Identifier (URI), identifies the resource to which it applies the request on the server. This target, which is based on the specification, can consist of multiple parts, including a host portion, path portion, query portion, and fragment portion. The Go net/url package contains logic for parsing a Unified Resource Locator (URL), as can be seen in the documentation: https://golang.org/pkg/net/url/.
-
Request HTTP version (RFC-7230 2.6): The HTTP version is the textual representation of the highest minor version within the major version of the protocol that the client is able to support. Within the Go net/http web server, this version information is populated in the request type.
The following is an example of the plain text HTTP request message which will GET the resource /file.txt from the web server, from which the client would like to navigate to the HTTP/1.1 protocol:
GET /file.txt HTTP/1.1
The first line in an HTTP message is known as the start-line of the HTTP message. If the message is a request type message, this line is more clearly known as the request-line of the message. As you can see in the Go documentation for the request type, the first five attributes of the http.Request type encompass the data from the start-line of the request: https://golang.org/pkg/net/http/#Request.
Additionally, and optionally, the request can contain the following data and metadata if applicable within the structure of the HTTP message:
- Request header fields (RFC-7230 3.2): Request header fields, known as just headers, are key/value pairs of metadata associated with either of the HTTP message types, request or response. This metadata is used to further describe attributes of the request, such as the length of the content body, or authentication credentials. The key/value pairs are separated by a : character, and are enumerated directly after the start-line of the message, one line per pair. There is a helpful list of registered headers that are commonly in use, which can provide guidance on request and response metadata. These registered headers are defined here: http://www.iana.org/assignments/message-headers. Within the http.Request type, there is a Header attribute which is a key to value mapping.
- Message body (RFC-7230 3.3): The message body is the payload of the request or response in the HTTP message protocol. The client and server are signaled the fact that the message body is present by the existence of the Content-Length or Transfer-Encoding headers. The Go web server implementation takes care of these headers automatically when a response is written to the response writer. The message body on a request is accessible from the Body attribute on the Request type in the net/http package. Of particular note here is that the Body is an implementation of the io.ReadCloser interface, which contains two methods: Read and Close.
The following is a more complete HTTP request message:
POST /file.txt HTTP/1.1
Host: localhost
Accept: */*
Content-Length: 8
Content-Type: application/x-www-form-urlencoded
hi=there
In the preceding example, the request dictates that we want to use the POST method on the `/file.txt` target resource. Our request headers specify that we are attempting to contact a particular host which is localhost, and are willing to accept any type of response content. Since we have a request body that is URL encoded, we need a Content-Type header specifying the content type as well as the length of the request body in bytes. Finally, our request body, hi=there, is submitted as the message body of the HTTP request message.
