Re: [whatwg/fetch] Editorial: Add prose about constructing a request (PR #1585)

@jyasskin commented on this pull request.

Here are my thoughts about how this should work, but you should prioritize opinions from people who've had trouble calling into fetch, like @tabatkins and @npm1.

> +that existed before the CORS mechanism was introduced. To use "<code>no-cors</code>" in a new
+feature, please discuss on the <a href=https://github.com/whatwg/fetch>Fetch Github repository</a>.

This should link somewhere more precise than the top level of the repository. @annevk/@domenic, do you want Issues for future proposals to use `no-cors`, or would it make more sense to enable Github Discussions for it?

> @@ -8380,6 +8380,56 @@ correctly. This section aims to give some advice.
 
 <p class=XXX>This is a work in progress.
 
+<h3 id=fetch-elsewhere-request>Constructing a request</h3>

We should link to here from https://fetch.spec.whatwg.org/#requests.

> @@ -8380,6 +8380,56 @@ correctly. This section aims to give some advice.
 
 <p class=XXX>This is a work in progress.
 
+<h3 id=fetch-elsewhere-request>Constructing a request</h3>
+
+<p>The first step in <a for=/>fetching</a> is to create a <a for=/>request</a>, and populate its
+multiple associated parameters.
+
+<p>A <a for=/>request</a> oftenmost has a <a for=request>client</a>, which is the
+<a>environment settings object</a> that initiatated the request, and the receiver of the different

I'm not sure it's always obvious which settings object "initiated the request". I think we could say that if a request is caused by a call into a platform object, it's the "relevant settings object" for that object. What other situations are there?
* The request is on behalf of the UA itself, for which we can ask people to see if https://github.com/whatwg/fetch/pull/1533 does what they need?
* The request is on behalf of an origin, but detached from any particular window, in which case maybe we want to check if that's really a good behavior for the web, and they should discuss it in this repo (see below for a question about how to organize such discussions)?
* Anything else? I haven't trawled through [uses of fetch](https://dontcallmedom.github.io/webdex/f.html#fetch%40%40fetch%25%25dfn) to collect more cases, but there probably are some.

> +<a>environment settings object</a> that initiatated the request, and the receiver of the different
+<a for=/>response</a> callbacks. It then expects a <a for=request>URL</a>, and an HTTP

I think we can skip the mention of response callbacks here and instead mention it in the "Invoking fetch" section.

> +<p>Requests accept an optional <a for=request>header list</a> parameter, custom HTTP headers to be
+sent alongside the <a for=/>request</a>. Note that sending custom headers may have implications,
+such as requiring a <a>CORS-preflight fetch</a>, so handle with care.

If we write this like `If you need to send custom HTTP headers in your request, put them in the [=request/header list=] parameter.` then we tell callers what to do , which should be easier for them to follow than if we just state facts about request objects.

> +<p>One of the most important things when constructing a <a for=/>request</a> is understanding how
+it's supposed to handle cross-origin resources. This is expressed in the <a for=/>request</a>'s
+<a for=request>mode</a>. Some features are supposed to work only in the context of the
+<a>same origin</a>, in which case the "<code>same-origin</code>" <a for=request>mode</a> is
+appropriate. For new features that require accessing cross-origin resources, "<code>cors</code>"

It might work better to write this as a [`<dl class="switch">`](https://w3c.github.io/tr-design/src/README#switch) with the options looking like 
```html
<dt>If the request's URL should be constrained to the same origin as its client's origin
<dd>Set [=request/mode=] to [=same origin=]
```

> +
+<p>Requests accept an optional <a for=request>header list</a> parameter, custom HTTP headers to be
+sent alongside the <a for=/>request</a>. Note that sending custom headers may have implications,
+such as requiring a <a>CORS-preflight fetch</a>, so handle with care.
+
+<p>One of the most important things when constructing a <a for=/>request</a> is understanding how
+it's supposed to handle cross-origin resources. This is expressed in the <a for=/>request</a>'s
+<a for=request>mode</a>. Some features are supposed to work only in the context of the
+<a>same origin</a>, in which case the "<code>same-origin</code>" <a for=request>mode</a> is
+appropriate. For new features that require accessing cross-origin resources, "<code>cors</code>"
+should be used, alongside a <a for=request>credentials mode</a>, which defines whether the
+<a for=/>request</a> is anonymous or authenticated (e.g. with cookies and client certificates). The
+"<code>no-cors</code>" <a for=request>mode</a> is used for backwards compatibility with features
+that existed before the CORS mechanism was introduced. To use "<code>no-cors</code>" in a new
+feature, please discuss on the <a href=https://github.com/whatwg/fetch>Fetch Github repository</a>.
+"<code>navigate</code>" and "<code>websocket</code>" are reserved for specific features.

Maybe don't even mention these. We could include something like "Other request modes can only be used by the feature they're named after." to head off questions.

> +<p>A <a for=/>request</a> accepts a few security-related parameters that are often configured, such
+as <a for=request>integrity metadata</a>, a string hash of the actual data that verifies that the
+received resource matches an expectation, a <a for=request>cryptographic nonce metadata</a> and
+<a for=request>parser metadata</a>, which allows more fine-grained security via
+<cite>Content Security Policy</cite>, and <a for=request>referrer policy</a>, which allows the
+<a for=/>request</a> to use a different <a for=/>referrer policy</a> from the one provided by the
+<a for=request>client</a>. [[!CSP]] [[!REFERRER]]

I'd give each of these a paragraph or an item in a [`<dl class="switch">`](https://w3c.github.io/tr-design/src/README#switch). Like 
> If you need to verify the received data hashes to a particular value, set [=request/integrity metadata=].

> @@ -8380,6 +8380,56 @@ correctly. This section aims to give some advice.
 
 <p class=XXX>This is a work in progress.
 
+<h3 id=fetch-elsewhere-request>Constructing a request</h3>

A high-level comment for the whole section, which I've elaborated on in several of the specific comments:

I think we want this section to be instructions to the authors of calling specifications -- a how-to guide. It might make sense to also improve the descriptive text in https://fetch.spec.whatwg.org/#requests, but that's not the primary hole this section needs to fill.

> +<a for=/>response</a> callbacks. It then expects a <a for=request>URL</a>, and an HTTP
+<a for=request>method</a>, `<code>GET</code>` by default. `<code>POST</code>` and
+`<code>PUT</code>` requests also accept a <a for=request>body</a>, which is sent together with the
+request.

These probably belong first:

> Start by setting the HTTP [=request/method=] and target [=request/URL=] as described in [[HTTP]]. If your `POST` or `PUT` request needs a body, you can assign or stream it to [=request/body=].

> +<p>A <a for=/>request</a> also accepts a few metadata parameters, the important one being
+<a for=request>destination</a>. <a for=request>destinations</a> affect

Perhaps:

> Set your request's [=request/destination=] according to how your specification is going to use the response. If you need a new destination, ...

This paragraph should link to the note that's under https://fetch.spec.whatwg.org/#request-destination-script-like that describes what each of the destinations and initiator types are for.

I think people are required to set their destination, in which case, this paragraph should appear before the optional parameters.

> +<a href=https://github.com/whatwg/fetch>Fetch Github repository</a>. An aditional metadata
+paramater is <a for=request>initiator type</a>, which specifies that the <a for=/>fetching</a>

Split this paragraph so people notice that they also need to set the initiator type. Do they always need to set it, or just if they want their resource to participate in [[resource-timing]]? Is the note under https://w3c.github.io/resource-timing/#dom-performanceresourcetiming-initiatortype the best description of how to set this?

-- 
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/fetch/pull/1585#pullrequestreview-1235132444
You are receiving this because you are subscribed to this thread.

Message ID: <whatwg/fetch/pull/1585/review/1235132444@github.com>