diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 4110ba8f..ef1b1045 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -54,8 +54,8 @@ in lowercase and still retain their meaning unless explicitly declared as non-normative. A conforming implementation of GraphQL over HTTP may provide additional -functionality, but must not where explicitly disallowed or would otherwise -result in non-conformance. +functionality, but must not do so where explicitly disallowed or where doing so +would otherwise result in non-conformance. **Non-Normative Portions** @@ -76,9 +76,9 @@ This is an example of a non-normative counter-example. ``` Notes in this document are non-normative, and are presented to clarify intent, -draw attention to potential edge-cases and pit-falls, and answer common -questions that arise during implementation. Notes are either introduced -explicitly in prose (e.g. "Note: ") or are set apart in a note block, like this: +draw attention to potential edge cases and pitfalls, and answer common questions +that arise during implementation. Notes are either introduced explicitly in +prose (e.g. "Note: ") or are set apart in a note block, like this: Note: This is an example of a non-normative note. @@ -200,7 +200,7 @@ parameters in one of the manners described in this specification: extend the protocol however they see fit, as specified in [the Response section of the GraphQL specification](https://spec.graphql.org/draft/#sec-Response-Format). -Note: When comparing _GraphQL-over-HTTP request_ against the term +Note: When comparing a _GraphQL-over-HTTP request_ against the term ["request"](https://spec.graphql.org/draft/#request) in the GraphQL specification you should note the _GraphQL schema_ and "initial value" are not included in the GraphQL-over-HTTP _request_; they are handled by the _server_ @@ -315,8 +315,8 @@ A client MUST indicate the media type of a request body using the `Content-Type` header; this header is specified in [IETF RFC 9110](https://httpwg.org/specs/rfc9110.html#field.content-type). -A server MUST support POST requests encoded with the `application/json` media -type (as indicated by the `Content-Type` header) encoded with UTF-8. +A server MUST support POST requests with a body encoded as UTF-8 JSON, using the +`application/json` media type (as indicated by the `Content-Type` header). For POST requests using an officially recognized GraphQL `Content-Type` without indicating an encoding, the server MUST assume the encoding is `utf-8`. @@ -326,7 +326,7 @@ server SHOULD reject the request using the appropriate `4xx` status code. Note: Rejecting such requests encourages clients to supply a `Content-Type` header with every POST request. A server has the option to assume any media type -they wish when none is supplied, with the understanding that parsing the request +it wishes when none is supplied, with the understanding that parsing the request may fail. A server MAY support POST requests encoded with and/or accepting other media @@ -406,12 +406,12 @@ And the body: # Response When a server receives a well-formed _GraphQL-over-HTTP request_, it must return -a well‐formed _GraphQL-over-HTTP response_. +a well-formed _GraphQL-over-HTTP response_. :: A _GraphQL-over-HTTP response_ is formed of the encoded _GraphQL result_ along with the relevant headers and status code. -:: A _GraphQL result_ describes the result of parsing, validating and (if +:: A _GraphQL result_ describes the result of parsing, validating, and (if successful) executing the requested operation, and any errors encountered during the request. If execution occurred then the GraphQL result represents a _GraphQL execution result_, otherwise (for example, in the case of parse or validation @@ -465,7 +465,7 @@ requirements of this specification as if the request had specified `Content-Type: application/json`. Note: This recommendation uses this specification's full range of HTTP status -codes whilst maximizing _legacy client_ compatibility for successful and +codes while maximizing _legacy client_ compatibility for successful and partially successful requests. HTTP responses could originate from non-GraphQL intermediary servers and middleware handling failures (HTTP `4xx` and `5xx`), so clients typically can only rely on a response to be from GraphQL either when it @@ -518,7 +518,7 @@ _GraphQL-over-HTTP response_ without needing to process the response body; this is useful in request logs, developer tooling, anomaly and intrusion detection, metrics and observability, API gateways, and more. -In case of errors that completely prevent the generation of a well-formed +In the case of errors that completely prevent the generation of a well-formed _GraphQL-over-HTTP response_, the server SHOULD respond with the appropriate HTTP `4xx` or `5xx` status code depending on the concrete error condition, and MUST NOT use the `application/graphql-response+json` media type. @@ -529,8 +529,8 @@ server MUST reply with a `2xx` status code. If the _GraphQL result_ contains the {data} entry and does not contain the {errors} entry, then the server SHOULD reply with a `200` status code. -Note: There are no circumstances where the GraphQL specification allows for a -_GraphQL result_ having {data} as {null} without {errors} being present. +Note: There are no circumstances where the GraphQL specification allows a +_GraphQL result_ to have {data} as {null} without {errors} being present. If the _GraphQL result_ contains both the {data} entry (even if it is {null}) and the {errors} entry, then the server SHOULD reply with a `294` status code. @@ -580,7 +580,7 @@ _GraphQL request error result_ and the server MUST reply with an appropriate - If the variable values cannot be coerced to match the operation's variable definitions, status code `422` SHOULD be used. - If the client is not permitted to issue the GraphQL request, then the server - SHOULD reply with `401`, `403` or similar appropriate status code. + SHOULD reply with `401`, `403`, or a similar appropriate status code. - If the server cannot process the request due to being a short and stout ceramic vessel, status code `418` SHOULD be used. - When the server is the reason for failure, the appropriate `5xx` status code @@ -594,7 +594,7 @@ entry is populated. Note: Implementers should be careful to always comply with the HTTP spec, for example when using status code `405` the `Allow` header MUST be specified, as -required by [RFC9110](https://httpwg.org/specs/rfc9110.html#status.405). +required by [RFC 9110](https://httpwg.org/specs/rfc9110.html#status.405). ### Examples @@ -646,8 +646,8 @@ SHOULD return a status code of `422` (Unprocessable Content). **Field errors encountered during execution** If the operation is executed and no _GraphQL request error_ is raised, then the -server SHOULD respond with a status code of `200` (Okay). This is the case even -if a _GraphQL execution error_ is raised during +server SHOULD respond with a status code of `200 OK`. This is the case even if a +_GraphQL execution error_ is raised during [GraphQL's ExecuteQuery()]() or [GraphQL's ExecuteMutation()](). @@ -780,5 +780,5 @@ other resources such as [OWASP](https://owasp.org). Supporting formats not described by this specification may have potential conflicts with future versions of this specification as ongoing development aims to standardize and ensure the security and interoperability of GraphQL over HTTP -whilst accounting for its growing feature set. For this reason, it is -recommended to adhere to the officially recognized formats outlined here. +while accounting for its growing feature set. For this reason, it is recommended +to adhere to the officially recognized formats outlined here.