OWD project: Update HTTP docs (HTTP/2, HTTP/3, CSP, etc)

[teoli2003]

This proposes that we work update HTTP documentation on MDN docs to take into account the HTTP/2 & HTTP/3 protocols, a move to Markdown, fix the outstanding issues, and revisions of the unclear areas (CSP, Cache…)

Problem statement

MDN docs articles about HTTP are now several years old. This area overall structure and content are still mostly in good shape and new features that appeared over the years (like Client-Hints for example) were added mostly smoothfully in that structure.

But HTTP has evolved over the years: HTTP/2 is now the most common version in use and HTTP/3 is in the progress of being released. We don't speak about these versions at all and that 1) leave our readers in the vague about these versions 2) makes MDN docs look outdated. We don't need to speak in all details about these protocols – a web dev doesn't need them – but we need at least:

1. An introduction for each of these two protocols;
2. Up-to-date glossaries entries for them, but also related technologies like QUIC;
3. Guide about advanced features and how to use them (Push functionalities?)

Also MDN docs get quite regularly issues about HTTP; there is currently a back-log of 23 issues, about 5% of the overall total, some of them pretty complex to solve.

HTTP docs, like the others area of MDN docs, have to move to Markdown as the devs won't want to keep it in HTML for long. There is a need edit consequently this area of the docs.

Priority assessment

This table checks this project against the OWD prioritization criteria.

Criteria	Assessment
Effort	Medium. We will write about 5-10 new articles overall, most of them (once HTTP/3 ships) low maintenance. There may be some untangling of complex articles and some revisions of the other articles (are the types of headers correctly set?). The whole area is 292 pages that will need to be reviewed and edited (but not completely rewritten)
Dependencies	No dependencies on the devs. A little bit of support for the migration to Markdown
Community enablement	Low, though updating templates may help our community to update it regularly.
Momentum	HTTP/3 has been released by default in several browsers, but not yet all. Having up-to-date docs when people look for novelty is always good.
Enabling learners	Only basic understanding of HTTP/3 will be provided
Enabling professionals	N/A
Underrepresented topics / ethical web	N/A
Operational necessities	The move to Markdown will have to happen anyway.
Addressing needs of the Web industry	N/A

Task list

1. Assess in details the HTTP area and make a proposal of new pages to be written, structural to be made.
2. Process with the minor restructuration
3. Add the 5-10 new articles
4. Update the area by resolving the HTTP-related issues on github.
5. Prepare for the Markdown migration (can be done in parallel with the other activities)
6. Migrate to Markdown
7. Review and fix details.

More information

Open Web Docs (OWD) is a non-profit collective funded by corporate and individual donations.

In order for this project to happen, please consider donating to OWD on https://opencollective.com/open-web-docs.
For more information on sponsorship and membership tiers, see https://openwebdocs.org/membership/

More information is available at https://openwebdocs.org.
For questions, please reach out to [email protected].

[hamishwillee]

I'm happy to help with some of this at your direction - don't feel sufficiently well informed yet on HTTP to lead it. One thing that occurs to me is that there are some headers that aren't relevant/drop in different versions. As most of them are relevant, we probably need a more systematic and obvious way of highlighting the ones that are not by HTTP version.

[teoli2003]

Here is the draft plan for documenting HTTP/2 on MDN. Everybody, please review and add comments to it.

Once the review process is over, I will post the task list in this Github issue (and execute the plan).

@mnot, @mcmanus, @reschke, @jasnell: you all have been referred to me as Subject Matter Experts (SME) by our members, and even if I have already interacted, and met, with some of you, I feel a bit intimidated.

I would be highly grateful if you would take some of your time to review the document, and I hope it is short enough. Having a 6-page introduction to HTTP/2 on MDN, trusted by many web developers, would help increase the overall knowledge about this protocol (and about HTTP/3 afterward) among people using it transparently every day.

Thank you in advance for your time, and feel free to comment in the document, or here, or to ask any question.

Link to the draft plan

[Elchi3]

Here is the draft plan for documenting HTTP/2 on MDN.

I'm capturing the information from this plan from 2021 from the Google doc into this GitHub issue (see below) in case anyone wants to pick up this work at some point. We currently don't plan to do this work, so I'm closing as not planned but feel free to talk to us about it if you're interested in this work.

---

Create new pages:

• HTTP/2 Overview
  This article presents the protocol. It stresses that it is a replacement for HTTP/1.1 and the problems it solves. It describes briefly how the version negotiation happens (ALPN) and informs that HTTP/2 is unavailable on non-encrypted transport or sessions. It notes that it is now a binary protocol with a brief explanation of messages, frames, and streams. It introduces the notions of HPACK, HTTP Prioritization, and Push notifications. Finally, it concludes with a description of problems not solved, leading to the future docs about HTTP/3.
  Note: This article is an overview, and we describe most concepts in more detail in the following articles.

• HTTP Messages
  This article describes HTTP/1.1 text messages and how they map to the binary structure of HTTP/2 frames and streams. We will update the existing page and add a few precisions (like that the chunked value of Transfer-Encoding is not available in HTTP/2).

• Connection management in HTTP/2
  This article describes the connection management in HTTP/2. How a browser sets up an HTTP/2 connection, how both peers agree to use HTTP/2, and how long it persists. It echoes Connection management in HTTP/1.x that will be adapted.

• HTTP Headers compression (HPACK)
  This page describes the algorithm's usefulness (linking to Patrick McManus research), mentions its resilience to CRIME, and describes its three mechanisms: the static dictionary, the dynamic dictionary, and the precomputed Huffman code.

• HTTP/2 Prioritization
  This article explains prioritization. It illustrates how priority is transmitted to the server (the three parameters) and describes the algorithms used by the different browsers. It notes that not all servers implement the algorithm correctly.

• HTTP Push notifications
  This page explains Push notifications and how they work. It clarifies that this feature is not implemented everywhere (and Google even considers its removal from Chrome).
  Note: Before starting the article's redaction, we will conduct additional research about Push notifications future. Chrome is considering removing this feature from HTTP/2 and already decided not to implement it in HTTP/3. What is the position of the other major browsers and the HTTPbis WG?

Create glossary entries: (non-exhaustive list)

• Man in the middle, or Manipulator in the middle (MiM or MitM) attack
• Head of line blocking (HOL)
• Application-layer protocol negotiation (ALPN)

Update pages:

• Evolution of HTTP (link)
• Update the HTTP/2 section.
• Overview of HTTP (link)
• Update to make the description matches HTTP/2 and link to the new pages when relevant.
• HTTP response status codes (link)
• Primarily add that HTTP/2 does not transmit the text associated with a status code anymore.
• 101 Switching Protocol (link)
• Add information that this status is no more in use in HTTP/2.
• Trailer: (link), Upgrade: (link) and Transfer-Encoding: (link)
  Update them with the changes and limitations to these headers in HTTP/2.

Other tasks:

• Add a mention in each reference page about a feature part of the static dictionary of HPACK, like the Accept-* headers or often-used status codes.
• Precise the stricter distinction between headers in header frames and headers in trailer frames in HTTP/2.