diff --git a/.gitignore b/.gitignore index e6772ab8..79845dc6 100644 --- a/.gitignore +++ b/.gitignore @@ -59,3 +59,15 @@ typings/ # Visual Studio project specific, machine local files .vs/ + +# Standard ignores from wg-template +*.swp +*~ +.*.haste_cache.* +.DS_Store +npm-debug.log +/build +/public +/gh-pages +yarn.lock +package-lock.json diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 00000000..1913c7be --- /dev/null +++ b/.prettierignore @@ -0,0 +1,4 @@ +# PRs to Working Group documents should be minimal effort - no need to force formatting compliance +/working-group/ +# To maintain the expressiveness of the original poster, we do not auto-format RFCs +/rfcs/ diff --git a/INTERESTED_DEVELOPERS.md b/INTERESTED_DEVELOPERS.md index dd6c3223..faafed0e 100644 --- a/INTERESTED_DEVELOPERS.md +++ b/INTERESTED_DEVELOPERS.md @@ -1,73 +1,88 @@ # Interested Developers -## Want to get involved? +## Want to get involved? -If you're interested in this spec and helping contribute to it, you can get involved with the following steps: +If you're interested in this spec and helping contribute to it, you can get +involved with the following steps: -1. Read the [Roadmap](ROADMAP.md) which outlines the planned development of this spec. -2. See [Agendas](working-group/agendas) for upcoming meetings of the GraphQL-over-HTTP working group. Given our world-wide span over many timezones, we are doing an experiment of attempting to advance the spec with fewer meetings and more asynchronous communication. During this experiment, please reach out over slack and github. +1. Read the [Roadmap](ROADMAP.md) which outlines the planned development of this + spec. +2. See [Agendas](working-group/agendas) for upcoming meetings of the + GraphQL-over-HTTP working group. Given our world-wide span over many + timezones, we are doing an experiment of attempting to advance the spec with + fewer meetings and more asynchronous communication. During this experiment, + please reach out over slack and github. 3. Add yourself to `List of Developers` below. -4. Find our working group on the [GraphQL Foundation slack community](https://slack.graphql.org) in the [graphql-over-http channel](https://graphql.slack.com/archives/CRTKLUZRT). +4. Find our working group on the + [GraphQL Foundation slack community](https://slack.graphql.org) in the + [graphql-over-http channel](https://graphql.slack.com/archives/CRTKLUZRT). ## List of Developers -This list helps us keep track people that are interested in taking decisions of the specification of GraphQL over HTTP. +This list helps us keep track people that are interested in taking decisions of +the specification of GraphQL over HTTP. -If you want to be listed here, open a PR with your information, just order yourself by username. +If you want to be listed here, open a PR with your information, just order +yourself by username. +- @abernix + - Company/Project/Repo: https://github.com/apollographql/apollo-server, + https://github.com/apollographql/apollo-client + - Reason: Interested in client/server spec +- @balshor + - Company/Project/Repo: https://github.com/linkedin + - Reason: Interested in a common HTTP spec +- @benjie + - Company/Project/Repo: https://github.com/graphql/graphiql, + https://github.com/graphile/postgraphile + - Reason: Interested in a common HTTP spec +- @deinok + - Company/Project/Repo: https://github.com/graphql-dotnet/graphql-client + - Reason: Interested in client/server on C# stack +- @enisdenjo + - Company/Project/Repo: https://github.com/domonda, + https://github.com/bhidapa, https://github.com/enisdenjo/graphql-ws + - Reason: Interested in a common subscriptions spec +- @erikwittern + - Company/Project/Repo: https://github.com/graphql/libgraphqlparser, + https://github.com/IBM/openapi-to-graphql + - Reason: Interested in client/server in JavaScript/C++ +- @ghmcadams + - Company/Project/Repo: https://github.com/ghmcadams + - Reason: Interested in a common HTTP spec +- @jaydenseric + - Company/Project/Repo: + https://github.com/jaydenseric/graphql-multipart-request-spec + - Reason: Interested in multipart request spec +- @maraisr + - Company/Project/Repo: https://github.com/maraisr/meros + - Reason: Interested in common incremental delivery spec +- @michaelstaib + - Company/Project/Repo: https://github.com/ChilliCream/hotchocolate + - Reason: Interested in client/server in JavaScript/C++/C# +- @mike-marcacci + - Company/Project/Repo: https://github.com/boltline + - Reason: Interested in client/server spec +- @mmatsa + - Company/Project/Repo: https://github.com/graphql/libgraphqlparser + - Reason: Interested in client/server in C++ +- @sjparsons + - Company/Project/Repo: PayPal & Braintree https://github.com/sjparsons + - Reason: Interested in common spec +- @spawnia + - Company/Project/Repo: https://github.com/nuwave/lighthouse + - Reason: Interested in client/server in PHP +- @sungam3r + - Company/Project/Repo: https://github.com/graphql-dotnet/server + - Reason: Interested in client/server spec +- @glennblock + - Company/Project/Report: https://github.com/microsoft + - Reason: Interested in a common HTTP spec, and in adoption of emerging HTTP + standards like HTTP SEARCH +- @hemanth + - Company/Project/Repo: PayPal https://github.com/hemanth + - Reason: Interested in a common HTTP spec and common subscriptions spec. -* @abernix - * Company/Project/Repo: https://github.com/apollographql/apollo-server, https://github.com/apollographql/apollo-client - * Reason: Interested in client/server spec -* @balshor - * Company/Project/Repo: https://github.com/linkedin - * Reason: Interested in a common HTTP spec -* @benjie - * Company/Project/Repo: https://github.com/graphql/graphiql, https://github.com/graphile/postgraphile - * Reason: Interested in a common HTTP spec -* @deinok - * Company/Project/Repo: https://github.com/graphql-dotnet/graphql-client - * Reason: Interested in client/server on C# stack -* @enisdenjo - * Company/Project/Repo: https://github.com/domonda, https://github.com/bhidapa, https://github.com/enisdenjo/graphql-ws - * Reason: Interested in a common subscriptions spec -* @erikwittern - * Company/Project/Repo: https://github.com/graphql/libgraphqlparser, https://github.com/IBM/openapi-to-graphql - * Reason: Interested in client/server in JavaScript/C++ -* @ghmcadams - * Company/Project/Repo: https://github.com/ghmcadams - * Reason: Interested in a common HTTP spec -* @jaydenseric - * Company/Project/Repo: https://github.com/jaydenseric/graphql-multipart-request-spec - * Reason: Interested in multipart request spec -* @maraisr - * Company/Project/Repo: https://github.com/maraisr/meros - * Reason: Interested in common incremental delivery spec -* @michaelstaib - * Company/Project/Repo: https://github.com/ChilliCream/hotchocolate - * Reason: Interested in client/server in JavaScript/C++/C# -* @mike-marcacci - * Company/Project/Repo: https://github.com/boltline - * Reason: Interested in client/server spec -* @mmatsa - * Company/Project/Repo: https://github.com/graphql/libgraphqlparser - * Reason: Interested in client/server in C++ -* @sjparsons - * Company/Project/Repo: PayPal & Braintree https://github.com/sjparsons - * Reason: Interested in common spec -* @spawnia - * Company/Project/Repo: https://github.com/nuwave/lighthouse - * Reason: Interested in client/server in PHP -* @sungam3r - * Company/Project/Repo: https://github.com/graphql-dotnet/server - * Reason: Interested in client/server spec -* @glennblock - * Company/Project/Report: https://github.com/microsoft - * Reason: Interested in a common HTTP spec, and in adoption of emerging HTTP standards like HTTP SEARCH -* @hemanth - * Company/Project/Repo: PayPal https://github.com/hemanth - * Reason: Interested in a common HTTP spec and common subscriptions spec. - ### CC Helper `@abernix @balshor @benjie @deinok @erikwittern @jaydenseric @michaelstaib @mike-marcacci @mmatsa @sjparsons @spawnia @sungam3r @enisdenjo` diff --git a/README.md b/README.md index 3c13c785..9f806d24 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,12 @@ > **Stage 0: Preliminary** -> -> This spec is in a preliminary stage of active development, and can change a lot before reaching `Draft` stage. For more information, please see the [Roadmap](ROADMAP.md) or [how to get involved](INTERESTED_DEVELOPERS.md). > -> You can find our community in the [graphql-over-http channel](https://discord.com/channels/625400653321076807/863141924126588958) on the [GraphQL Foundation Discord](https://discord.graphql.org). +> This spec is in a preliminary stage of active development, and can change a +> lot before reaching `Draft` stage. For more information, please see the +> [Roadmap](ROADMAP.md) or [how to get involved](INTERESTED_DEVELOPERS.md). +> +> You can find our community in the +> [graphql-over-http channel](https://discord.com/channels/625400653321076807/863141924126588958) +> on the [GraphQL Foundation Discord](https://discord.graphql.org). --- @@ -10,33 +14,59 @@ **Introduction** -HTTP is the most common choice as the client-server protocol when using GraphQL because of its ubiquity. -However the [GraphQL specification](https://graphql.github.io/graphql-spec/) deliberately does not specify the transport layer. +HTTP is the most common choice as the client-server protocol when using GraphQL +because of its ubiquity. However the +[GraphQL specification](https://graphql.github.io/graphql-spec/) deliberately +does not specify the transport layer. -The closest thing to an official specification is the article [Serving over HTTP](https://graphql.org/learn/serving-over-http/). -Leading implementations on both client and server have mostly upheld those best practices and thus established -a de-facto standard that is commonly used throughout the ecosystem. +The closest thing to an official specification is the article +[Serving over HTTP](https://graphql.org/learn/serving-over-http/). Leading +implementations on both client and server have mostly upheld those best +practices and thus established a de-facto standard that is commonly used +throughout the ecosystem. -This specification is intended to fill this gap by specifying how GraphQL should be served over HTTP. -The main intention of this specification is to provide interoperability between different client libraries, tools -and server implementations. +This specification is intended to fill this gap by specifying how GraphQL should +be served over HTTP. The main intention of this specification is to provide +interoperability between different client libraries, tools and server +implementations. **Spec Location** -The GraphQL over HTTP specification is edited in the [spec-md markdown file](./spec/GraphQLOverHTTP.md). +The GraphQL over HTTP specification is edited in the +[spec-md markdown file](./spec/GraphQLOverHTTP.md). -In the future, we plan that you would be able to view the generated form of the specification as well. +In the future, we plan that you would be able to view the generated form of the +specification as well. ### Contributing to this repo -This repository is managed by EasyCLA. Project participants must sign the free ([GraphQL Specification Membership agreement](https://preview-spec-membership.graphql.org) before making a contribution. You only need to do this one time, and it can be signed by [individual contributors](https://individual-spec-membership.graphql.org/) or their [employers](https://corporate-spec-membership.graphql.org/). +This repository is managed by EasyCLA. Project participants must sign the free +([GraphQL Specification Membership agreement](https://preview-spec-membership.graphql.org) +before making a contribution. You only need to do this one time, and it can be +signed by +[individual contributors](https://individual-spec-membership.graphql.org/) or +their [employers](https://corporate-spec-membership.graphql.org/). -To initiate the signature process please open a PR against this repo. The EasyCLA bot will block the merge if we still need a membership agreement from you. +To initiate the signature process please open a PR against this repo. The +EasyCLA bot will block the merge if we still need a membership agreement from +you. -You can find [detailed information here](https://github.com/graphql/graphql-wg/tree/main/membership). If you have issues, please email [operations@graphql.org](mailto:operations@graphql.org). +You can find +[detailed information here](https://github.com/graphql/graphql-wg/tree/main/membership). +If you have issues, please email +[operations@graphql.org](mailto:operations@graphql.org). -If your company benefits from GraphQL and you would like to provide essential financial support for the systems and people that power our community, please also consider membership in the [GraphQL Foundation](https://foundation.graphql.org/join). +If your company benefits from GraphQL and you would like to provide essential +financial support for the systems and people that power our community, please +also consider membership in the +[GraphQL Foundation](https://foundation.graphql.org/join). --- + Copyright Joint Development Foundation Projects, LLC, GraphQL Series.
-[graphql.org](https://graphql.org) | [Spec](https://spec.graphql.org) | [GitHub](https://github.com/graphql/graphql-over-http) | [GraphQL Foundation](https://foundation.graphql.org) | [Code of Conduct](https://code-of-conduct.graphql.org) | [Discord](https://discord.com/channels/625400653321076807/863141924126588958) | [Store](https://store.graphql.org) +[graphql.org](https://graphql.org) | [Spec](https://spec.graphql.org) | +[GitHub](https://github.com/graphql/graphql-over-http) | +[GraphQL Foundation](https://foundation.graphql.org) | +[Code of Conduct](https://code-of-conduct.graphql.org) | +[Discord](https://discord.com/channels/625400653321076807/863141924126588958) | +[Store](https://store.graphql.org) diff --git a/ROADMAP.md b/ROADMAP.md index 1a4ab62d..5fdfc663 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -2,20 +2,24 @@ ## Mission -_Provide a specification that allows GraphQL clients and servers with different implementations and technology stacks to interact freely over HTTP if both client and server are compliant._ +_Provide a specification that allows GraphQL clients and servers with different +implementations and technology stacks to interact freely over HTTP if both +client and server are compliant._ ## Guiding principles - Development is based on use cases - Strive for backwards-compatible progress - - Servers supporting later versions of this spec should support clients using earlier versions of this spec. + - Servers supporting later versions of this spec should support clients using + earlier versions of this spec. ## Version 1.0 -After significant meetings, the Working Group has come to consensus that a first version of this spec should -introduce some key changes over the prior existing uses of GraphQL over HTTP. -This first version _might_ also codify existing prior common usages of GraphQL over HTTP. -In layout and structure version 1.0 should lay a foundation for future development and standardization. +After significant meetings, the Working Group has come to consensus that a first +version of this spec should introduce some key changes over the prior existing +uses of GraphQL over HTTP. This first version _might_ also codify existing prior +common usages of GraphQL over HTTP. In layout and structure version 1.0 should +lay a foundation for future development and standardization. ### Scope @@ -28,7 +32,8 @@ In layout and structure version 1.0 should lay a foundation for future developme ### Actions - Move to the GraphQL Foundation -- Set of running examples of ~5 of the most popular servers/clients with a standard, minimal GraphQL schema +- Set of running examples of ~5 of the most popular servers/clients with a + standard, minimal GraphQL schema - Test suite to automate testing of GraphQL servers compliance with the spec - Can be applied to examples of popular server or public GraphQL APIs - Results of popular libraries and APIs compliance with current spec @@ -43,42 +48,52 @@ Future versions of the spec may include these concepts: - Caching - Batching -- Versioning mechanism for servers/clients to communicate what versions they support -- Modularity - A way to communicate what features (and possibly versions) of the HTTP spec are supported by a server +- Versioning mechanism for servers/clients to communicate what versions they + support +- Modularity - A way to communicate what features (and possibly versions) of the + HTTP spec are supported by a server - Persisted queries - Multipart requests (file uploads) - Submit MIME type application/graphql+json to IANA -- New HTTP SEARCH method and how it could be used https://tools.ietf.org/html/draft-snell-search-method-01 +- New HTTP SEARCH method and how it could be used + https://tools.ietf.org/html/draft-snell-search-method-01 ## Stages -The process of writing this specification may proceed according this rough outline of stages. -We are currently in the *Preliminary Stage*. +The process of writing this specification may proceed according this rough +outline of stages. We are currently in the _Preliminary Stage_. ### Stage 0: Preliminary -In the *Preliminary Stage*, things may change rapidly and no one should count on any particular -detail remaining the same. +In the _Preliminary Stage_, things may change rapidly and no one should count on +any particular detail remaining the same. -- If a PR has no requests for changes for 2 weeks then it should be merged by one of the maintainers -- If anyone has an objection later, they just open a PR to make the change and it goes through the same process +- If a PR has no requests for changes for 2 weeks then it should be merged by + one of the maintainers +- If anyone has an objection later, they just open a PR to make the change and + it goes through the same process - Optional: When there is lots of consensus but not 100% full consensus then: - - We might merge the consensus-view and debate modifying it in parallel - - Anyone can extract the non-controversial part and make a separate PR + - We might merge the consensus-view and debate modifying it in parallel + - Anyone can extract the non-controversial part and make a separate PR -When the spec seems stable enough, the working group would promote it to *Proposal Stage*. +When the spec seems stable enough, the working group would promote it to +_Proposal Stage_. ### Stage 1: Proposal -In the *Proposal Stage*, things can still change but it is reasonable to start implementations. +In the _Proposal Stage_, things can still change but it is reasonable to start +implementations. -- Before release of the spec, in "Draft" stage, we have to review the spec and review all open PRs +- Before release of the spec, in "Draft" stage, we have to review the spec and + review all open PRs - Every merge to master would need strong consensus - Only changes that address concerns - Implementers could start trying things -After the spec and open PRs are reviewed and there is strong consensus, the working group would promote it to *Draft Stage*. +After the spec and open PRs are reviewed and there is strong consensus, the +working group would promote it to _Draft Stage_. ### Stage 2: Draft -This corresponds to the general [GraphQL Draft Stage](https://github.com/graphql/graphql-spec/blob/master/CONTRIBUTING.md#stage-2-draft) +This corresponds to the general +[GraphQL Draft Stage](https://github.com/graphql/graphql-spec/blob/master/CONTRIBUTING.md#stage-2-draft) diff --git a/cspell.yml b/cspell.yml new file mode 100644 index 00000000..8fcd02dc --- /dev/null +++ b/cspell.yml @@ -0,0 +1,16 @@ +language: en-US +ignoreRegExpList: + # Posessives + - /[a-z]{2,}'s/ +words: + # Terms of art + - endianness + - interoperation + - monospace + - openwebfoundation + - parallelization + - structs + - subselection + # Software + - ical + # Fictional characters / examples diff --git a/package.json b/package.json new file mode 100644 index 00000000..10f9e57f --- /dev/null +++ b/package.json @@ -0,0 +1,18 @@ +{ + "name": "graphql-over-http", + "private": true, + "license": "OWFa-1.0", + "scripts": { + "test:spellcheck": "cspell \"**/*.md\"", + "format": "prettier --write \"**/*.{md,yml,yaml,json}\"", + "format:check": "prettier --check \"**/*.{md,yml,yaml,json}\"" + }, + "devDependencies": { + "cspell": "5.9.1", + "prettier": "^2.6.2" + }, + "prettier": { + "proseWrap": "always", + "trailingComma": "none" + } +} diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 490b1712..010f6be5 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -1,9 +1,13 @@ -GraphQL Over HTTP ------------------ +## GraphQL Over HTTP -Note: **Stage 0: Preliminary** -This spec is under active development, and not ready for implementations yet. For more information, please see the [Roadmap](https://github.com/APIs-guru/graphql-over-http/blob/master/ROADMAP.md) or [how to get involved](https://github.com/APIs-guru/graphql-over-http/blob/master/INTERESTED_DEVELOPERS.md). -You can find our community in the [graphql-over-http channel](https://graphql.slack.com/archives/CRTKLUZRT) on the [GraphQL Foundation slack](https://slack.graphql.org). +Note: **Stage 0: Preliminary** This spec is under active development, and not +ready for implementations yet. For more information, please see the +[Roadmap](https://github.com/APIs-guru/graphql-over-http/blob/master/ROADMAP.md) +or +[how to get involved](https://github.com/APIs-guru/graphql-over-http/blob/master/INTERESTED_DEVELOPERS.md). +You can find our community in the +[graphql-over-http channel](https://graphql.slack.com/archives/CRTKLUZRT) on the +[GraphQL Foundation slack](https://slack.graphql.org). --- @@ -11,16 +15,21 @@ You can find our community in the [graphql-over-http channel](https://graphql.sl **Introduction** -HTTP is the most common choice as the client-server protocol when using GraphQL because of its ubiquity. -However the [GraphQL specification](https://graphql.github.io/graphql-spec/) deliberately does not specify the transport layer. +HTTP is the most common choice as the client-server protocol when using GraphQL +because of its ubiquity. However the +[GraphQL specification](https://graphql.github.io/graphql-spec/) deliberately +does not specify the transport layer. -The closest thing to an official specification is the article [Serving over HTTP](https://graphql.org/learn/serving-over-http/). -Leading implementations on both client and server have mostly upheld those best practices and thus established -a de-facto standard that is commonly used throughout the ecosystem. +The closest thing to an official specification is the article +[Serving over HTTP](https://graphql.org/learn/serving-over-http/). Leading +implementations on both client and server have mostly upheld those best +practices and thus established a de-facto standard that is commonly used +throughout the ecosystem. -This specification is intended to fill this gap by specifying how GraphQL should be served over HTTP. -The main intention of this specification is to provide interoperability between different client libraries, tools -and server implementations. +This specification is intended to fill this gap by specifying how GraphQL should +be served over HTTP. The main intention of this specification is to provide +interoperability between different client libraries, tools and server +implementations. **Copyright notice** @@ -28,30 +37,30 @@ and server implementations. **Conformance** -A conforming implementation of GraphQL over HTTP must fulfill all normative requirements. -Conformance requirements are described in this document via both +A conforming implementation of GraphQL over HTTP must fulfill all normative +requirements. Conformance requirements are described in this document via both descriptive assertions and key words with clearly defined meanings. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative portions of -this document are to be interpreted as described in [IETF RFC 2119](https://tools.ietf.org/html/rfc2119). -These key words may appear in lowercase and still retain their meaning unless -explicitly declared as non-normative. +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative portions of +this document are to be interpreted as described in +[IETF RFC 2119](https://tools.ietf.org/html/rfc2119). These key words may appear +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 it would otherwise result -in non-conformance. +A conforming implementation of GraphQL over HTTP may provide additional +functionality, but must not where explicitly disallowed or it would otherwise +result in non-conformance. **Non-Normative Portions** -All contents of this document are normative except portions explicitly -declared as non-normative. +All contents of this document are normative except portions explicitly declared +as non-normative. Examples in this document are non-normative, and are presented to aid understanding of introduced concepts and the behavior of normative portions of -the specification. Examples are either introduced explicitly in prose -(e.g. "for example") or are set apart in example or counter-example blocks, -like this: +the specification. Examples are either introduced explicitly in prose (e.g. "for +example") or are set apart in example or counter-example blocks, like this: ```example This is an example of a non-normative example. @@ -70,33 +79,39 @@ Note: This is an example of a non-normative note. # Overview -Serving GraphQL over HTTP provides the ability to use the full advantages of GraphQL with the rich feature set of HTTP. -Carrying GraphQL in HTTP does not mean that GraphQL overrides existing semantics of HTTP, -but rather that the semantics of GraphQL over HTTP map naturally to HTTP semantics. +Serving GraphQL over HTTP provides the ability to use the full advantages of +GraphQL with the rich feature set of HTTP. Carrying GraphQL in HTTP does not +mean that GraphQL overrides existing semantics of HTTP, but rather that the +semantics of GraphQL over HTTP map naturally to HTTP semantics. -GraphQL naturally follows the HTTP request/response message model, -providing a GraphQL request in an HTTP request and GraphQL response in an HTTP response. +GraphQL naturally follows the HTTP request/response message model, providing a +GraphQL request in an HTTP request and GraphQL response in an HTTP response. # URL -A GraphQL over HTTP compliant server MUST designate at least one URL that handles GraphQL requests. +A GraphQL over HTTP compliant server MUST designate at least one URL that +handles GraphQL requests. -A GraphQL schema allows clients to know the available operations on a GraphQL server. -Clients can discover the schema by sending an introspection query, which the server MUST answer with a proper response. +A GraphQL schema allows clients to know the available operations on a GraphQL +server. Clients can discover the schema by sending an introspection query, which +the server MUST answer with a proper response. -The schema on a single URL MAY not be the same for every client. -For example, certain fields could be restricted to authenticated users or alpha testers. +The schema on a single URL MAY not be the same for every client. For example, +certain fields could be restricted to authenticated users or alpha testers. -All Queries and Mutations a client discovered in the schema MUST be available on the same URL. -That means the client can send all their GraphQL requests to a single endpoint. +All Queries and Mutations a client discovered in the schema MUST be available on +the same URL. That means the client can send all their GraphQL requests to a +single endpoint. -Multiple URLs MAY exist on a server to handle GraphQL requests, potentially serving different -but self-sufficient schemas. The same GraphQL schema MAY be available on multiple URLs on the server. +Multiple URLs MAY exist on a server to handle GraphQL requests, potentially +serving different but self-sufficient schemas. The same GraphQL schema MAY be +available on multiple URLs on the server. -Those URLs MAY also be used for other purposes, as long as they don't conflict with the -server's responsibility to handle GraphQL requests. +Those URLs MAY also be used for other purposes, as long as they don't conflict +with the server's responsibility to handle GraphQL requests. -It is RECOMMENDED to end the path component of the URL with `/graphql`, for example: +It is RECOMMENDED to end the path component of the URL with `/graphql`, for +example: ```url example http://example.com/graphql @@ -112,54 +127,81 @@ http://example.com/product/graphql # Serialization Format -The GraphQL specification allows for many [serialization formats to be implemented](https://spec.graphql.org/October2021/#sec-Serialization-Format). Servers and clients over HTTP MUST support JSON and MAY support other, additional serialization formats. +The GraphQL specification allows for many +[serialization formats to be implemented](https://spec.graphql.org/October2021/#sec-Serialization-Format). +Servers and clients over HTTP MUST support JSON and MAY support other, +additional serialization formats. -For consistency and ease of notation, examples of the response are given in JSON throughout the spec. +For consistency and ease of notation, examples of the response are given in JSON +throughout the spec. ## Content Types -The following are the officially recognized GraphQL content types to designate encoding JSON over HTTP. +The following are the officially recognized GraphQL content types to designate +encoding JSON over HTTP. -| Name | Description | -| ------------- | ------------- | -| `application/graphql+json` | Required | -| `application/json` | To support legacy clients | +| Name | Description | +| -------------------------- | ------------------------- | +| `application/graphql+json` | Required | +| `application/json` | To support legacy clients | -A server MUST support requests from clients with HTTP header `Content-Type: application/graphql+json` indicating that the body of the request is a JSON document with a GraphQL request. A server must indicate the content type of the response with a `Content-Type` header. This default value should be `Content-Type: application/graphql+json` indicating that the response is a valid JSON document [conforming to the GraphQL spec](https://spec.graphql.org/October2021/#sec-Response-Format). +A server MUST support requests from clients with HTTP header +`Content-Type: application/graphql+json` indicating that the body of the request +is a JSON document with a GraphQL request. A server must indicate the content +type of the response with a `Content-Type` header. This default value should be +`Content-Type: application/graphql+json` indicating that the response is a valid +JSON document +[conforming to the GraphQL spec](https://spec.graphql.org/October2021/#sec-Response-Format). A server MAY support requests from clients with other content types. -A client MUST handle receiving responses with HTTP header `Content-Type: application/graphql+json` since any compliant server must support this type. +A client MUST handle receiving responses with HTTP header +`Content-Type: application/graphql+json` since any compliant server must support +this type. -This header MAY include encoding information (e.g. `Content-Type: application/graphql+json; charset=utf-8`) +This header MAY include encoding information (e.g. +`Content-Type: application/graphql+json; charset=utf-8`) # Request -A server MUST accept POST requests, and MAY accept other HTTP methods, such as GET. +A server MUST accept POST requests, and MAY accept other HTTP methods, such as +GET. ## Request Parameters A request for execution should contain the following request parameters: -* {query} - A Document containing GraphQL Operations and Fragments to execute. -* {operationName} - (*Optional*): The name of the Operation in the Document to execute. -* {variables} - (*Optional*): Values for any Variables defined by the Operation. -* {extensions} - (*Optional*): This entry is reserved for implementors to extend the protocol however they see fit. +- {query} - A Document containing GraphQL Operations and Fragments to execute. +- {operationName} - (_Optional_): The name of the Operation in the Document to + execute. +- {variables} - (_Optional_): Values for any Variables defined by the Operation. +- {extensions} - (_Optional_): This entry is reserved for implementors to extend + the protocol however they see fit. -Note: Be aware that `query` is a misleading name as it can contain a string describing multiple 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. +Note: Be aware that `query` is a misleading name as it can contain a string +describing multiple 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. -Note: depending on the serialization format used, values of the aforementioned parameters can be -encoded differently but their names and semantics must stay the same. +Note: depending on the serialization format used, values of the aforementioned +parameters can be encoded differently but their names and semantics must stay +the same. -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: 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 its value. ## GET -For HTTP GET requests, the query parameters MUST be provided in the query component of the request URL in the form of -`key=value` pairs with `&` symbol as a separator and both the key and value should have their "reserved" characters percent-encoded as specified in [section 2 of RFC3986](https://tools.ietf.org/html/rfc3986#section-2). -The `variables` parameter, if used, MUST be represented as a URL-encoded JSON string. +For HTTP GET requests, the query parameters MUST be provided in the query +component of the request URL in the form of `key=value` pairs with `&` symbol as +a separator and both the key and value should have their "reserved" characters +percent-encoded as specified in +[section 2 of RFC3986](https://tools.ietf.org/html/rfc3986#section-2). The +`variables` parameter, if used, MUST be represented as a URL-encoded JSON +string. ### Example @@ -167,7 +209,7 @@ If we wanted to execute the following GraphQL query: ```graphql example query ($id: ID!) { - user(id:$id) { + user(id: $id) { name } } @@ -177,7 +219,7 @@ With the following query variables: ```json example { - "id" : "QVBJcy5ndXJ1" + "id": "QVBJcy5ndXJ1" } ``` @@ -187,20 +229,31 @@ This request could be sent via an HTTP GET as follows: http://example.com/graphql?query=query(%24id%3A%20ID!)%7Buser(id%3A%24id)%7Bname%7D%7D&variables=%7B%22id%22%3A%22QVBJcy5ndXJ1%22%7D ``` -Note: {query} and {operationName} parameters are encoded as raw strings in the query component. Therefore if the query string contained `operationName=null` then it should be interpreted as the {operationName} being the string `"null"`. If a literal `null` is desired, the parameter (e.g. {operationName}) should be omitted. - -GET requests MUST NOT be used for executing mutation operations. If the values of {query} and {operationName} indicate that a mutation operation is to be executed, the server SHOULD immediately respond with error status code `405` (Method Not Allowed) and halt execution. This restriction is necessary to conform with the long-established semantics of safe methods within HTTP. +Note: {query} and {operationName} parameters are encoded as raw strings in the +query component. Therefore if the query string contained `operationName=null` +then it should be interpreted as the {operationName} being the string `"null"`. +If a literal `null` is desired, the parameter (e.g. {operationName}) should be +omitted. +GET requests MUST NOT be used for executing mutation operations. If the values +of {query} and {operationName} indicate that a mutation operation is to be +executed, the server SHOULD immediately respond with error status code `405` +(Method Not Allowed) and halt execution. This restriction is necessary to +conform with the long-established semantics of safe methods within HTTP. ## POST -A GraphQL POST request instructs the server to perform a query or mutation operation. A GraphQL POST request MUST have a body which contains values of the request parameters encoded according to the value of `Content-Type` header of the request. +A GraphQL POST request instructs the server to perform a query or mutation +operation. A GraphQL POST request MUST have a body which contains values of the +request parameters encoded according to the value of `Content-Type` header of +the request. A client MUST include a `Content-Type` with a POST request. ### Example -Given a POST request with a content type of `application/graphql+json` here is an example request body: +Given a POST request with a content type of `application/graphql+json` here is +an example request body: ```json example { @@ -211,68 +264,91 @@ Given a POST request with a content type of `application/graphql+json` here is a # Response -When a GraphQL server receives a request, it must return a well‐formed response. The server's -response describes the result of executing the requested operation if successful, and describes -any errors encountered during the request. +When a GraphQL server receives a request, it must return a well‐formed response. +The server's response describes the result of executing the requested operation +if successful, and describes any errors encountered during the request. ## Body -If the server's response contains a body it should follow the requirements for [GraphQL response](https://graphql.github.io/graphql-spec/October2021/#sec-Response). +If the server's response contains a body it should follow the requirements for +[GraphQL response](https://graphql.github.io/graphql-spec/October2021/#sec-Response). -A server MUST return a `Content-Type` HTTP Header with a value of a valid GraphQL content type. If there is no `Accept` header in the request, the response MUST be serialized as JSON and MUST include a `Content-Type: application/graphql+json` header. +A server MUST return a `Content-Type` HTTP Header with a value of a valid +GraphQL content type. If there is no `Accept` header in the request, the +response MUST be serialized as JSON and MUST include a +`Content-Type: application/graphql+json` header. -If another content type is preferable to a client, it MAY include an `Accept` HTTP header listing other acceptable content types in order of preference. In this case a client SHOULD include `application/graphql+json` in the list, according to their preferred priority. +If another content type is preferable to a client, it MAY include an `Accept` +HTTP header listing other acceptable content types in order of preference. In +this case a client SHOULD include `application/graphql+json` in the list, +according to their preferred priority. -The server MUST respect the given `Accept` header and attempt to encode the response in the first supported content type listed. According to the [HTTP 1.1 Accept](https://tools.ietf.org/html/rfc7231#section-5.3.2) specification, when a client does not include at least one supported content type in the `Accept` HTTP header, the server MAY choose to respond in one of several ways. The server MUST either: +The server MUST respect the given `Accept` header and attempt to encode the +response in the first supported content type listed. According to the +[HTTP 1.1 Accept](https://tools.ietf.org/html/rfc7231#section-5.3.2) +specification, when a client does not include at least one supported content +type in the `Accept` HTTP header, the server MAY choose to respond in one of +several ways. The server MUST either: -1. Disregard the `Accept` header and respond with the default content type of `application/graphql+json`, specifying this in the `Content-Type` header; OR +1. Disregard the `Accept` header and respond with the default content type of + `application/graphql+json`, specifying this in the `Content-Type` header; OR 2. Respond with a `406 Not Acceptable` status code -Note: For any non-`2XX` response, the client should not rely on the body to be in GraphQL format since the source of the response -may not be the GraphQL server but instead some intermediary such as API gateways, firewalls, etc. +Note: For any non-`2XX` response, the client should not rely on the body to be +in GraphQL format since the source of the response may not be the GraphQL server +but instead some intermediary such as API gateways, firewalls, etc. ## Status Codes If the response has Content-Type GraphQL and contains a non-null `data` entry, -then it MUST have status code `2xx`, and it SHOULD have status code `200` (Okay). +then it MUST have status code `2xx`, and it SHOULD have status code `200` +(Okay). + +If the response has Content-Type GraphQL and has a non-`2xx` status code, the +`data` entry must be either: -If the response has Content-Type GraphQL and has a non-`2xx` status code, -the `data` entry must be either: - equal to `null` - not present -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 response. +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 response. -In case of errors that completely prevent the successful execution of the request, -the server SHOULD respond with the appropriate status code depending on the concrete error condition. +In case of errors that completely prevent the successful execution of the +request, the server SHOULD respond with the appropriate status code depending on +the concrete error condition. -The following examples provide guidance on how to deal with specific error cases: +The following examples provide guidance on how to deal with specific error +cases: ### Unparseable or invalid request body For example: `NONSENSE`, `{"qeury": "{__typena` -Completely prevents execution of the GraphQL operation and SHOULD result in status code `400` (Bad Request). +Completely prevents execution of the GraphQL operation and SHOULD result in +status code `400` (Bad Request). ### Document validation Includes validation steps that run before execution of the GraphQL operation: + - [GraphQL specification validation](https://spec.graphql.org/October2021/#sec-Validation) - custom validation, for example: depth limit, complexity limit The server SHOULD deny execution with a status code of `400` (Bad Request). -Note: In certain circumstances, for example persisted queries that were previously -known to be valid, the server MAY attempt execution regardless of validation errors. +Note: In certain circumstances, for example persisted queries that were +previously known to be valid, the server MAY attempt execution regardless of +validation errors. ### Runtime validation -Validation steps performed by resolvers during execution of the GraphQL operation. +Validation steps performed by resolvers during execution of the GraphQL +operation. -The server SHOULD respond with a status code of `200` (Okay) to ensure clients receive -a predictable result, no matter which fields they selected. +The server SHOULD respond with a status code of `200` (Okay) to ensure clients +receive a predictable result, no matter which fields they selected. ### Client is not allowed to access the schema