Overhaul massive inline note by moving much to section 7

Author: benjie

spec/GraphQLOverHTTP.md

@@ -647,9 +647,21 @@ should be added to the above.
 
 ### application/graphql-response+json
 
-This section only applies when the response body is to use the
+This section only applies when the response body uses the
 `application/graphql-response+json` media type.
 
+With this media type, clients should process the response as a well-formed
+_GraphQL response_ independent of the HTTP status code, and should read the
+response body (specifically {data} and {errors}) to determine the status of the
+response.
+
+Note: The purpose of setting a status code is to aid intermediary services and
+tooling (which may not implement this specification) in understanding the rough
+status of a response. This is useful in request logs, anomaly and intrusion
+detection, metrics and observability, API gateways, and more. The status code is
+not intended to aid the client, in fact it is recommended the client ignore the
+status code when this media type is in use.
+
 If the _GraphQL response_ contains the {data} entry and it is not {null}, then
 the server MUST reply with a `2xx` status code.
 
@@ -665,24 +677,11 @@ and the {errors} entry, then the server SHOULD reply with `203` status code.
 Note: The result of executing a GraphQL operation may contain partial data as
 well as encountered errors. Errors that happen during execution of the GraphQL
 operation typically become part of the result, as long as the server is still
-able to produce a well-formed _GraphQL response_. There's currently not an
-approved official HTTP status code to use for a "partial success," contenders
-include "206 Partial Content" (which requires the `Range` header), WebDAV's
-status code "207 Multi-Status", and using a custom code such as "294 Partial
-Success."
-[IETF RFC2616 Section 6.1.1](https://datatracker.ietf.org/doc/html/rfc2616#section-6.1.1)
-states "codes are fully defined in section 10" implying that though more codes
-are expected to be supported over time, valid codes must be present in this
-document. For compatibility reasons, using `203` seems to work the best with
-intermediate servers and clients. We hope to one day move to `294` if someone
-can push it through the IETF review process. Using `4xx` and `5xx` status codes
-in this situation is not appropriate - since no _GraphQL request error_ has
-occurred it is seen as a "partial response" or "partial success". Note that this
-use of HTTP 203 does not strictly align with the intended semantics of this
-status code, but was a pragmatic choice to maximize compatibility whilst
-allowing servers to indicate partial success such that intermediaries that do
-not implement this specification may still track the not-fully-successful
-request (for example, for anomaly detection).
+able to produce a well-formed _GraphQL response_. For details of why status code
+`203` is recommended, see [Partial success](#sec-Partial-success). Using `4xx`
+and `5xx` status codes in this situation is not appropriate - since no _GraphQL
+request error_ has occurred it is seen as a "partial response" or "partial
+success".
 
 If the _GraphQL response_ does not contain the {data} entry then the server MUST
 reply with a `4xx` or `5xx` status code as appropriate.
@@ -697,21 +696,6 @@ pass validation, then the server SHOULD reply with `400` status code.
 If the client is not permitted to issue the GraphQL request then the server
 SHOULD reply with `403`, `401` or similar appropriate status code.
 
-Note: When the response media type is `application/graphql-response+json`,
-clients can rely on the response being a well-formed _GraphQL response_
-regardless of the status code. Intermediary servers may use the status code to
-determine the status of the _GraphQL response_ without needing to process the
-response body.
-
-A client should process a GraphQL response that uses the
-`application/graphql-response+json` media type independent of which HTTP status
-code it uses, instead reading the response body to determine how to handle the
-request.
-
-Note: For the avoidance of doubt, GraphQL clients, once they have established
-that the response uses `application/graphql-response+json`, should completely
-ignore the HTTP status code.
-
 #### Examples
 
 The following examples provide guidance on how to deal with specific error cases
@@ -801,6 +785,38 @@ is met:
 - the response media type is `application/graphql-response+json`, or
 - the status code is `200`.
 
+## Partial success
+
+The result of executing a GraphQL operation may contain partial data as well as
+encountered errors. Errors that happen during execution of the GraphQL operation
+typically become part of the result, as long as the server is still able to
+produce a well-formed _GraphQL response_.
+
+Using `4xx` and `5xx` status codes when {data} is present and non-null is not
+appropriate; since no _GraphQL request error_ has occurred it is seen as a
+"partial response" or "partial success".
+
+There's currently not an approved official HTTP status code to use for a
+"partial success," contenders include "206 Partial Content" (which requires the
+`Range` header), WebDAV's status code "207 Multi-Status", and using a custom
+code such as "294 Partial Success."
+
+[IETF RFC2616 Section 6.1.1](https://datatracker.ietf.org/doc/html/rfc2616#section-6.1.1)
+states "codes are fully defined in section 10" implying that though more codes
+are expected to be supported over time, valid codes must be present in this
+document. For compatibility reasons, using HTTP status `203` which has no
+additional requirements seems to work the best with intermediate servers and
+clients, but since it does not semantically line up we only recommend its usage
+alongside the `application/graphql-response+json` media type which makes the
+meaning explicit. We hope to one day move to `294` if someone can push it
+through the IETF review process.
+
+Note that this use of HTTP 203 does not strictly align with the intended
+semantics of this status code, but was a pragmatic choice to maximize
+compatibility whilst allowing servers to indicate partial success such that
+intermediaries that do not implement this specification may still track the
+not-fully-successful request (for example, for observability).
+
 ## Security
 
 This specification focuses solely on the intersection of GraphQL and HTTP.