What is the HTTP header :host, :method, :path, :scheme, :version used for?

Understanding HTTP/2 Pseudo-Headers: :authority, :method, :path, :scheme, :status

Explore the critical role of HTTP/2 pseudo-headers in defining request and response semantics, and how they differ from traditional HTTP/1.x headers.

In the evolution of the Hypertext Transfer Protocol, HTTP/2 introduced significant changes to improve performance and efficiency. One of the most notable, yet often misunderstood, aspects is the concept of pseudo-headers. Unlike traditional HTTP/1.x headers, which are key-value pairs sent in plain text, pseudo-headers in HTTP/2 are special fields prefixed with a colon (:) that convey essential request and response metadata. These headers are not arbitrary; they are fundamental to how HTTP/2 frames are constructed and interpreted.

The Role of Pseudo-Headers in HTTP/2

HTTP/2 pseudo-headers replace parts of the HTTP/1.x request line and status line, providing a more structured and efficient way to transmit this information. They are always present in HTTP/2 request and response headers and are crucial for the protocol's operation. These headers are never forwarded to the origin server as traditional headers; instead, they are processed by the HTTP/2 layer and translated into the appropriate HTTP/1.x equivalents if the request is downgraded or proxied.

sequenceDiagram
    participant Client
    participant Proxy/Gateway
    participant Server

    Client->>Proxy/Gateway: HTTP/2 Request (with :method, :scheme, :authority, :path)
    Proxy/Gateway-->>Client: HTTP/2 Response (with :status)
    Proxy/Gateway->>Server: HTTP/1.1 Request (GET /path HTTP/1.1\r\nHost: example.com)
    Server-->>Proxy/Gateway: HTTP/1.1 Response (HTTP/1.1 200 OK)
    Note over Proxy/Gateway: Translates pseudo-headers to HTTP/1.1 format for origin server

HTTP/2 Pseudo-Header Translation in a Proxy Scenario

Key HTTP/2 Pseudo-Headers Explained

Let's break down the individual pseudo-headers and their significance:

:method

This pseudo-header carries the HTTP request method, such as GET, POST, PUT, DELETE, etc. It directly corresponds to the method part of the HTTP/1.x request line.

:scheme

This indicates the scheme of the target URI, typically http or https. It's crucial for understanding how the connection was established and for security contexts.

:authority

Similar to the Host header in HTTP/1.x, :authority specifies the host and optional port of the target URI. It's used for routing and virtual hosting. For requests, it's mandatory unless the target URI is an absolute URI and the host component is present in the :path.

:path

This pseudo-header contains the path and query components of the target URI. For example, /index.html?query=value. It directly maps to the path part of the HTTP/1.x request line.

:status

This pseudo-header is unique to HTTP/2 responses. It carries the three-digit HTTP status code (e.g., 200, 404, 500), replacing the status line in HTTP/1.x responses. It's the first header field in any HTTP/2 response.

Distinction from HTTP/1.x Headers

It's vital to understand that pseudo-headers are not interchangeable with their HTTP/1.x counterparts. They exist at a different layer of the protocol stack. When an HTTP/2 request is translated to HTTP/1.x (e.g., by a proxy), the pseudo-headers are converted into the appropriate request line and Host header. Conversely, an HTTP/1.x request received by an HTTP/2 gateway will have its request line and Host header translated into HTTP/2 pseudo-headers.

GET /path/to/resource?query=value HTTP/1.1
Host: example.com
User-Agent: MyClient/1.0
Accept: */*

---

:method: GET
:scheme: https
:authority: example.com
:path: /path/to/resource?query=value
user-agent: MyClient/1.0
accept: */*

Comparison of HTTP/1.1 Request (top) and HTTP/2 Request (bottom) headers.

Impact on Development and Debugging

For most web developers, the presence of pseudo-headers is largely transparent. Browsers and HTTP clients handle their generation and interpretation automatically. However, when working with low-level HTTP/2 implementations, proxies, or debugging tools, understanding pseudo-headers becomes essential. Tools like curl with the --http2 flag or browser developer tools will often display these pseudo-headers, providing insight into the underlying HTTP/2 communication.

curl -v --http2 https://www.example.com/

# Excerpt from curl output showing pseudo-headers:
# > GET / HTTP/2
# > Host: www.example.com
# > user-agent: curl/7.64.1
# > accept: */*
# > 
# * Connection state changed (MAX_CONCURRENT_STREAMS == 128) 
# < HTTP/2 200 
# < date: Thu, 01 Jan 1970 00:00:00 GMT
# < content-type: text/html; charset=UTF-8

Using curl to observe HTTP/2 pseudo-headers in a request and response.