Upgrade
The Upgrade
is used to transition the HTTP connection into another protocol, such as a WebSocket.
Usage in requests
The Upgrade
header in a request lists any number of protocols.
Writing requests (clients)
The Upgrade header is typically used to establish WebSocket connections, but can be used for any protocol identified by a protocol-name
. Write an Upgrade header listing any number of protocols, in decending order of preference.
This is a hop-by-hop header, and so must be listed in the Connection header.
Reading requests (servers)
Servers should pick particular resources (particular URIs) that are used for protocol changes. Servers encountering an Upgrade header can ignore it, unless the resource is configured to switch to a different protocol. In this case, pick the first protocol from the list that is understood, and respond with 101 (Switching Protocols) listing the selected protocol in a response Upgrade
header.
Usage in responses
In responses, the Upgrade
header lists the protocol that the server selected.
Writing responses (servers)
Servers include the Upgrade header in responses that will switch protocols at the. The header must only be used with a 101 Switching Protocols status code, and only a protocol listed by the client.
Reading responses (clients)
The header lists the protocol selected by the server. The new protocol takes effect immediately following the blank line. If there is an error in reading the response headers, just close the TCP connection.
Overview table
- Name
- Upgrade
- Description
- Request that the server transition to another protocol.
- Direction
- Both
- Negotiates
- Upgrade
- Negotiated by
- Upgrade
- List usage in
- Connection
- Specification
- RFC 7230: HTTP/1.1: Message Syntax and Routing ยง6.7. Upgrade
Syntax
Upgrade = 1#protocol
protocol = protocol-name ["/" protocol-version]
protocol-name = token
protocol-version = token
Example
GET /hello.txt HTTP/1.1
Host: www.example.com
Connection: upgrade
Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11
If the server understands the first protocol listed (here, HTTP/2.0
), it will . Any data after the end of the request message will be consumed by the new protocol, and all data after the response message is from the new protocol:
HTTP/1.1 101 Switching Protocols
Connection: upgrade
Upgrade: HTTP/2.0
[... data stream switches to HTTP/2.0 with an appropriate response
(as defined by new protocol) to the "GET /hello.txt" request ...]