Upgrade header field may be used by clients to invite a server to switch to one (or more) of the listed protocols, in descending preference order.
For example, the client might send a
GET request as shown, listing the preferred protocols to switch to (in this case "example/1" and "foo/2"):
Connection: upgrade must be set whenever
Upgrade is sent.
The server can choose to ignore the request, for any reason, in which case it should just respond as though the
Upgrade header had not been sent (for example, with a
If the server decides to upgrade the connection, it must:
- Send back a
101 Switching Protocols response status with an
Upgrade header that specifies the protocol(s) being switched to. For example:
HTTP/1.1 101 Switching Protocols
- Send a response to the original request using the new protocol (the server may only switch to a protocol with which it can complete the original request).
A server may also send the header as part of a
Upgrade Required response, to indicate that the server won't perform the request using the current protocol, but might do so if the protocol is changed. The client can then request a protocol change using the process above.
More detail and examples are provided in the topic Protocol upgrade mechanism.