HTTP Headers
Upgrade
HTTP Header
The HTTP Upgrade request and response header are used to transition an already-established client/server connection to a different protocol over the same transport. This feature allows, for example, upgrading a connection from HTTP/1.1 to HTTP/2, or changing an HTTP(S) connection to a WebSocket connection.
The Header type includes both request and response headers. However, certain headers, such as some request headers, are forbidden during the upgrade process.
Syntax
A comma-separated list of one or more protocols:
Upgrade: <protocol>[/<protocol_version>]
Upgrade: <protocol>[/<protocol_version>], …, <protocolN>[/<protocol_versionN>]
Directives
Protocols are listed, comma-separated, in order of descending preference.
An optional protocol version may be provided prefixed with a forward slash (/).
Example
The Upgrade header field allows clients to request that the server switch to one or more protocols listed in order of preference. For instance, a client might send a GET request like this, indicating preferred protocols such as example/1 and foo/2:
GET /index.html HTTP/1.1
Host: www.example.com
Connection: upgrade
Upgrade: example/1, foo/2The server can choose to ignore the upgrade request, in which case it responds as if the Upgrade header was not sent, typically with a 200 OK response. If the server is willing to upgrade the connection, it must:
- Respond with a 101 Switching Protocols status code, including an
Upgradeheader specifying the protocol to switch to. For example:HTTP/1.1 101 Switching Protocols Upgrade: foo/2 Connection: Upgrade - Respond to the original request using the new protocol, provided the server supports it and can handle the request accordingly.
A server might also include the Upgrade header in a 426 Upgrade Required response, indicating it cannot process the request with the current protocol but might do so if the protocol is changed. The client can then attempt a protocol upgrade as described above.
Additional details and examples are provided in the section Protocol upgrade mechanism.
Upgrade header with multiple protocols
The following request demonstrates listing multiple protocols in order of descending preference:
Connection: upgrade
Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11Upgrading to WebSocket
This is a common set of headers used to upgrade an HTTP connection t a WebSocket connection. For more information, see Upgrading to a WebSocket connection.
Connection: Upgrade
Upgrade: websocketHow to Modify Header using Requestly
Requestly is a powerful Chrome extension that allows you to modify HTTP headers, including the Upgrade header. This is especially useful for testing how your application handles protocol upgrades like switching from HTTP to WebSocket. Steps to Modify the Upgrade Header:
- Install and open the Requestly Chrome extension. You can find it on the Chrome Web Store.
- Create a new rule: Click on “Create Rule” and choose “Modify Headers” from the list of available rule types.
- Add a new header modification:
- Under “Action”, select “Add” or “Override”.
- In the “Header Name” field, enter Upgrade.
- In the “Header Value” field, enter your desired protocol (e.g., websocket).
- Set the URL condition: Specify the URL or pattern where this header change should apply (e.g., https://your-api.com/*).
- Save the rule.
Once set up, Requestly will inject the Upgrade: websocket header into all matching requests, allowing you to simulate protocol upgrade requests and test how your server responds to them.
Modifying the Upgrade header helps you test features like WebSocket connections or other protocol switches, which is important for developing real-time applications or debugging communication issues.
Table of Contents
- No headings found.
