--- url: /statelake/scripting-reference/http-scripting/anatomy-of-an-http-request.md --- # Anatomy Of An HTTP Request ## Request-Line The **Request-Line** is the single line that describes the request, and has three (3) elements which are all separated by a space, but does not include the host. See the examples below. 1. **HTTP Method** – describes the action to be performed, such as **GET**, **PUT**, **POST**, **HEAD**, and **OPTIONS**. For example, **GET** indicates that a resource should be fetched, while **POST** indicates that data is to be pushed to the server to create or edit a resource, or create a temporary document to send back. ```pascal POST / HTTP/1.1 ``` ```pascal GET /background.png HTTP/1.0 ``` ```pascal HEAD /test.html?query-alibaba HTTP/1.1 ``` ```pascal OPTIONS /anypage.html HTTP/1.0 ``` ### Methods | HTTP Method | Description | |---|---| | GET | Used to retrieve the information from the server by sending a URL request with no **Message Body**. A query string can be included in the URL, and should be made use of. | | POST | Used to send information to the server. Sends a **Message Body** as part of a request to the URL. A query string can be included in the URL. The URL specifies a script/program that will handle the request. **POST** tells the URL to process the **Message Body**.**POST** requests support both query and path parameters. However, it's best practice to avoid query parameters for **POSTs** in REST APIs. This keeps the request data together in the body and avoids potential issues with parameter encoding and caching. Instead, use path parameters to identify resources and put the remaining data in the request body as JSON. | | HEAD | It does not return any content but is used to check whether the resource has changed, or what is the size or type of the resource. Similar to a **GET** request, but the server only returns the header and not the actual resource. This is useful if you want to check for the existence of a URL without downloading it. | | PUT | Used to create or update the resource at a particular URL known by the client. This particular URI is referred to as Request-URI. Sends a **Message Body** to the URL, which can include a query string. The specified URL is the location for the file to be uploaded to. The update data itself should go in the request body, as **PUT** says to upload the **Message Body** to the specified URL. **PUT** requests should avoid query parameters and use path parameters to identify the resource being updated. | | DELETE | Used to delete the resource identified by the Request-URI. This is the reverse of **PUT**. **DELETE** requests should use path parameters to identify the resource being deleted. Query parameters are not commonly used with **DELETE**.::: warningBe aware that it cannot be guaranteed that the operation has been carried out, even though the **Status-Code** from the server indicates that the action has been completed successfully.::: | | CONNECT | Used when an https URL is requested. It is used to establish a tunnel to the server identified by the given resource URI. | | OPTIONS | To find which request method a server supports, **OPTIONS** is used. It is used to describe the communication option for the target resource. One can specify whether to communicate to the whole server, or to a particular URL. To communicate over the whole server use an asterisk ( \* ). | | TRACE | It is similar to the **traceroot** command. It echoes back to the server whatever string is sent to the server for debugging purposes. The response to this method includes a list of the servers that handled the message. Should never include a **Message Body**. | 2. **Path/Query String** – the format varies depending on the **HTTP Method**. It can be in the form of : 1. An absolute path, ultimately followed by a question mark ( ? ) and a query string. This is the most common form, known as the *origin form*, and is used with **GET**, **POST**, **HEAD**, and **OPTIONS** methods. 2. A complete URL, known as the *absolute form*, that is mostly used with **GET** when connected to a proxy. ```pascal GET https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages HTTP/1.1 ``` 3. The authority component of a URL, consisting of the domain name and optionally the port prefixed by a colon ( : ) , which is called the *authority form*. It is only used with **CONNECT** when setting up an HTTP tunnel. ```pascal CONNECT developer.mozilla.org:80 HTTP/1.1 ``` 4. The *asterisk form*, a simple asterisk ( \* ) is used with **OPTIONS**, representing the server as a whole. ```pascal OPTIONS * HTTP/1.1 ``` 3. **Protocol** – indicates the expected **HTTP** version to use for the response, and defines the structure of the message. In modern browsers this is HTTP/1.1. ## Message Headers Message Headers are optional. There are many different headers that can appear in a request. Always just a single line, they consist of a header string followed by a colon, and then a value. They contain extra information about the type of connection being made, including the host, authentication tokens, cookies, Content-Type (for a post request), user-agent, and various accept headers. *Examples of the different Message Headers* * **Request Headers** – such as **Host**, **If-None-Match**, or **Accept-Language** modify the request by specifying greater detail. ```pascal Host: www.google.co.nz ``` * **General Headers** – like **Connection** or **Via** apply to the message as a whole. ```pascal X-Auth-token: blah-blah-blah ``` * **Representation Headers** – describe the original format of the message data and any encoding that has been applied, such as **Content-Type** or **Content-length**. These are only present of there is a Message Body. ```pascal Content-Type: text/csv ``` The correct **Content-Type** header must be set for **POST** and **PUT** methods. There are 2 different XML headers that could be used. The application/xml content-type is the preferred option. This is because the text/xml type requires an extra html header to define the character set, and ignores the character set defined in the document. If no **Content-Type** is defined, content is assumed to be *us-ascii* - using *application/xml* as the **Content-Type** respects the character set as defined in the xml document. ### Content-Type | Type | Header | |---|---| | XML | Content-Type: application/xml (preferred option)Content-Type: text/xml | | JSON | Content-Type: application/json | | CSV | Content-Type: text/csv | | TXT | Content-Type: text/plain | | HTML | Content-Type: text/html | | Binary | Content-Type: application/octet-stream (generic, check for specific type) | ## Blank Line A **Blank Line** must be included between the headers and **Message Body**, and should be included even if the headers and/or body are omitted. It indicates that all meta-information for the request has been sent. The **Blank Line** is a CR/LF, as are all end-of-line markers in HTTP 1.1. ## Message Body The **Message Body** is the data that is to be sent with the **Request-Line** and any headers, but it is optional because it is not used by some **HTTP** methods. Unlike the **Start-Lines** and **Message Headers** which are textual and structured, along with text, the body can also contain arbitrary binary data (e.g., images, videos, audio tracks, software applications). **POST** and **PUT** request methods need a **Message Body**, as this is the component being sent to ask the server to create a resource to contain the requested data. **GET** and **HEAD** normally do not need a **Message Body**. And even though it is technically possible to send data to the server using **GET** and the query string, it should be avoided and **POST** will be preferable. Sending large amounts of data using **GET** is impractical, and has limitations. **TRACE** should never have a **Message Body**. For **REST** connections, the body will often be XML, JSON or CSV.