Upgrade

L'en-tête HTTP Upgrade, réservé à HTTP/1.1, peut être utilisé pour basculer une connexion client/serveur déjà établie sur un autre protocole (en conservant le même protocole de transport). Un client pourra par exemple utiliser cet en-tête pour demander la mise à niveau de la connexion HTTP/1.1 en HTTP/2 ou le passage d'une connexion HTTP ou HTTPS à une connexion WebSocket.

Attention : HTTP/2 interdit explicitement l'usage de cet en-tête et de ce mécanisme. Il est réservé à HTTP/1.1.

Type d'en-tête En-tête de requête, en-tête de réponse.
Nom d'en-tête interdit Oui

Description

L'en-tête Upgrade pourra être utilisé par les clients pour inviter un serveur à basculer sur l'un des protocoles indiqués dans na liste triée par ordre de préférence décroissant.

Un client pourra par exemple envoyer la requête GET suivante, indiquant les protocoles préférés vers lesquels basculer (ici, exemple/1, puis toto/2) :

http
GET /index.html HTTP/1.1
Host: www.example.com
Connection: upgrade
Upgrade: exemple/1, toto/2

Note : L'en-tête Connection: upgrade doit être présent lorsqu'Upgrade est envoyé.

Le serveur est libre d'ignorer la requête et répondre alors comme si l'en-tête Upgrade n'avait pas été envoyé (par exemple avec un statut 200 OK).

Si le serveur décide de mettre à niveau la connexion, il doit :

  1. Renvoyer une réponse avec le statut 101 Switching Protocols et qui contient un en-tête Upgrade indiquant le(s) protocole(s) sur le(s)quel(s) basculer. Par exemple :
    http
    HTTP/1.1 101 Switching Protocols
    Upgrade: toto/2
    Connection: Upgrade
    
  2. Envoyer une réponse à la requête originelle en utilisant le nouveau protocole (le serveur ne peut basculer sur un protocole que s'il est en mesure de répondre à la requête originelle avec celui-ci).

Un serveur pourra également envoyer cet en-tête lors d'une réponse 426 Upgrade Required pour indiquer que le serveur ne traitera pas la requête avec le protocole actuel, mais pourrait le faire si le protocole était changé. Le client peut alors initier un changement de protocole comme vu ci-avant.

Pour plus de détails et d'exemples, voir l'article sur le mécanisme de mise à niveau du protocole.

Syntaxe

http
Connection: upgrade
Upgrade: protocol_name[/protocol_version]

Notes :

  • L'en-tête Connection doit toujours être envoyé avec la valeur upgrade lorsque l'en-tête Upgrade est envoyé.
  • Les protocoles indiqués en valeurs forment une liste, séparée par des virgules, et triée par ordre de préférence décroissant. La version du protocole est optionnelle. Par exemple :
http
Connection: upgrade
Upgrade: un_protocole/1, exemple, un_autre_protocole/2.2

Directives

Une liste de noms de protocoles (avec une version optionnelle), séparés par des virgules. La liste est triée par ordre de préférence décroissant.

Exemples

http
Connection: upgrade
Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11
http
Connection: Upgrade
Upgrade: websocket

Spécifications

Specification
HTTP Semantics
# field.upgrade
HTTP Semantics
# status.426
HTTP/2
# informational-responses

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi