HTTP Protocol Upgrade Mechanism

The HTTP/1.1 protocol includes a facility to upgrade the current connection to a higher one, such as HTTP/2, or for the creation of Websockets.

Usage

Client-side request

A protocol upgrade is initiated by using the Upgrade HTTP request header. It can be employed to transition from the current HTTP/1.1 connection to another protocol without having to terminate the HTTP Connection. The client can list more than one desired protocol, with the protocol order matching the order of preference.

This is a hop-by-hop header, which implies that it also needs to be listed in the Connection HTTP request header. Additional HTTP headers may need to change, depending on the protocol. For example, the Websocket protocol falls into this category.

This functionality is specific to HTTP/1.1 and is optional, and thus cannot be forced. A specific implementation can opt to let the current protocol remain, even if it supports that which is specified in the upgrade request.

When a server successfully upgrades the HTTP Connection, it returns the 101 Switching Protocols informational HTTP response status code. The new protocol is also included. Once the client receives this HTTP status code, it can immediately begin using the upgraded protocol. The original HTTP request can simply continue with the new protocol in place.

Note

If the server cannot or is unwilling to upgrade the HTTP Connection, it ignores the Upgrade header and returns the HTTP response that will otherwise describe the result. This means that a HTTP request that includes the Upgrade header can receive a 200 OK response in return, yet the protocol does not change.

Server-side request

Although a server supports HTTP/1.1, there may be reasons that it is unwilling to satisfy certain HTTP requests. For example, a server may want to better protect a confidential resource using a secure HTTP Connection, such as HTTPS, and will demand a protocol upgrade before fulfilling the HTTP request. In this case, in response to an HTTP/1.1 request, the server will return the 426 Upgrade Required HTTP status code.

There is no guarantee that the server will satisfy the HTTP request, even if the upgrade is successful, but it may be willing to.

Example

In this example, the client requests that the HTTP Connection be upgraded to HTTP/2 or HTTP/3. The server acknowledges the HTTP request and upgrades the protocol to HTTP/2, after which, the HTTP request continues where it left off but with the new protocol.

Request

GET /news.html HTTP/1.1
Host: www.example.re
Connection: upgrade
Upgrade: HTTP/2, HTTP/3

Response

HTTP/1.1 101 Switching Protocols
Upgrade: HTTP/2
Connection: upgrade

Takeaway

HTTP/1.1 includes a protocol upgrade feature that allows the client to change protocols without having to terminate the current HTTP Connection and create a new one. Using the Upgrade and Connection HTTP headers, in combination with HTTP response status codes 101 Switching Protocols and 426 Upgrade Required, protocols can sometimes be upgraded for different or more secure operations.

Last updated: August 2, 2023