From 71ddf4702e751303ad502bce21dd98cb45840a6b Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Mon, 11 Jul 2022 14:52:01 +0100 Subject: [PATCH 1/2] Editorial recommendations from @glasser --- spec/GraphQLOverHTTP.md | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index b71ecb09..df5094d1 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -216,9 +216,9 @@ included in the GraphQL-over-HTTP _request_, they are handled by the _server_ based on the URL used. Note: Be aware that `query` is a misleading parameter name as its value is a -string describing one or more operations, each of which may be a query, mutation -or subscription. A better name would have been `document`, but the term `query` -is well established. +string describing one or more operations, each of which may be a query or +mutation. A better name would have been `document`, but the term `query` is well +established. Note: Depending on the serialization format used, values of the aforementioned parameters can be encoded differently but their names and semantics must stay @@ -228,7 +228,8 @@ Note: Specifying `null` in JSON (or equivalent values in other formats) as values for optional request parameters is equivalent to not specifying them at all. -Note: {variables} and {extensions}, if set, must have a map as their value. +Note: Each of the {variables} and {extensions} parameters, if set, must have a +map as their value. ## Accept @@ -262,8 +263,10 @@ The `query` parameter MUST be the string representation of the Source Text of the Document as specified in [the Language section of the GraphQL specification](https://spec.graphql.org/draft/#sec-Language). -The `variables` parameter, if used, MUST be represented as a URL-encoded JSON -string. +The `operationName`, if present, must be a string. + +Each of the `variables` and `extensions` parameters, if used, MUST be +represented as a URL-encoded JSON string. ### Example @@ -373,10 +376,10 @@ And the body: # Response -When a server receives a GraphQL request, it must return a well‐formed response. -The server's response describes the result of validating and executing the -requested operation if successful, and describes any errors encountered during -the request. +When a server receives a {GraphQL-over-HTTP request}, it must return a +well‐formed response. The server's response describes the result of validating +and executing the requested operation if successful, and describes any errors +encountered during the request. A server must comply with [RFC7231](https://datatracker.ietf.org/doc/html/rfc7231). @@ -534,9 +537,9 @@ The following examples provide guidance on how to deal with specific error cases when using the `application/graphql+json` media type to encode the response body: -##### Invalid request body or parsing failure +##### Invalid parameters or parsing failure -For example: `NONSENSE`, `{"qeury": "{__typena` +For example a POST response body of `NONSENSE` or `{"qeury": "{__typena`. Requests that do not constitute a well-formed GraphQL request should result in status code `400` (Bad Request). From 2635324c5354b40b9629a3b6b384cf22a1bf220c Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Mon, 11 Jul 2022 15:50:11 +0100 Subject: [PATCH 2/2] Fix spec-md syntax --- spec/GraphQLOverHTTP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index df5094d1..60e0faa7 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -376,7 +376,7 @@ And the body: # Response -When a server receives a {GraphQL-over-HTTP request}, it must return a +When a server receives a _GraphQL-over-HTTP request_, it must return a well‐formed response. The server's response describes the result of validating and executing the requested operation if successful, and describes any errors encountered during the request.