GET

The HTTP GET method is a type of HTTP request that is used to retrieve a representation of a resource from a server. This is the primary operation used for retrieving information, and in many cases, it is the only interaction that a client will have with a server.

Usage

A HTTP request of this type is sent to retrieve data, and there is no message body included. The values are generally limited to 255 characters in length, and it only supports string data types.

The specification does not explicitly forbid including data with the HTTP request, although it is not good practice to do so because the semantics are undefined. In fact, some implementations will reject HTTP requests that include a message body.

It is expected that the HTTP GET method will return a response in the message body. In cases where the message is not required, such as for testing the validity of a hyperlink, consider using the HTTP HEAD or CONNECT methods instead.

The results of a HTTP GET request are cacheable and because it is read-only, this is intended to be a safe HTTP method. It is idempotent because identical calls made successively will leave the server in the same state as it was after the first one. The results can also be bookmarked and the parameters remain in the web browser’s history.

In practice, albeit discouraged, an HTTP GET request can cause data to be altered on the server by way of side effects. For example, if a call to a specific URL can be used to alter or delete a resource, then visits from a web crawler can inadvertently do so. A trivial example is the updating of a “visitor counter” whenever an HTTP GET request is made to the server. The HTTP request is still considered safe and idempotent because the client did not ask for the side effect.

Example

This simple example fetches the root page from the specified URL. The final line is the empty line, indicating that the HTTP header field list is complete. Once the HTTP request is sent in its entirety, the server will process it and return the HTTP response.

Request

GET / HTTP/1.1
Host: www.example.re

Conditional GET

The HTTP request changes to a Conditional GET if the request message body includes one of the following validators: If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since, If-Range. A Conditional GET will only retrieve the data if the conditions specified by the validators are met.

If the HTTP request successfully retrieves data after testing the validator(s) then it will return with a HTTP status code of 200 OK. For validators If-Match and If-Modified-Since, failure is indicated using the 304 Not Modified status code. In this case, the data will not be returned. This is beneficial in that it conserves bandwidth.

In the event that the If-None-Match or If-Unmodified-Since validators fail, the 412 Precondition Failed status code is returned. Finally, the If-Range validator will cause the server to return a status code of 206 Partial Content for a successful HTTP request, and if the condition is not fulfilled then a 200 OK will be returned.

Example Conditional GET

This example is the same as the previous one without the If-Modified-Since validator, and the server will only process the HTTP request if indeed the resource has been altered since the specified date and time.

Request

GET / HTTP/1.1
Host: www.example.re
If-Modified-Since: 01 Jan 2021 12:00:00 GMT

Partial GET

The HTTP request changes to a Partial GET if there is a Range specifier included. This type of HTTP request asks that only a subset of the data is returned. A 206 Partial Content indicates success, whereas a 416 Range Not Satisfiable error will be returned upon failure. Alternatively, the server will return a 200 OK status along with the entire document if it does not support the Range header field.

Example Partial GET

In this example, the client is requesting that only the first 512 bytes of the resource be returned, as specified by the HTTP Range request header.

Request

GET / HTTP/1.1
Host: www.example.re
Range: bytes=0-511

Takeaway

The HTTP GET request method is the primary operation used for information retrieval. It is safe, idempotent, and the results are cacheable. A Conditional GET uses one or more validators to instruct the server not to send resources unnecessarily, and a Range Request can be used to send only part of a resource.

See also

Last updated: August 2, 2023