Rework specification with a focus on backwards compatibility (#175)

* Start editing spec

* GraphQL server -> server; GraphQL client -> client

* Content-Types

* Request edits

* Rework Content-Types and start work on Response

* Status codes differ between media types

* Special case for data:null

* Update wording around status codes

* Revisions from second read-through

* Another editing pass

* Update spec/GraphQLOverHTTP.md

* Apply suggestions from code review

Co-authored-by: Gabriel McAdams <[email protected]>

* Clarify server parsing (suggestion by @ghmcadams)

* Move media type rules to media type section

* Prettier

* Move 'JSON Encoding' section into POST section

* 'X in the GraphQL specification' -> 'GraphQL's X'

* -we

* Correct typo

* Add @ghmcadams' suggestions (modified)

* Reword

* Apply @spawnia's improvement

Co-authored-by: Benedikt Franke <[email protected]>

* You must assume UTF-8 (thanks @spawnia)

Co-authored-by: Benedikt Franke <[email protected]>

* Client MUST indicate Content-Type - thanks @michaelstaib

* Make it clearer we're referring to a term

* Prettier

* Grammar (thanks @spawnia)

Co-authored-by: Benedikt Franke <[email protected]>

* Fix the formatting of POST example

* Clarify non-normative note about authorization decisions

* Clarification around client Accept header

* Consistently format variables

* Remove 'application/graphql+json' as encoding of request body

* Move the "AS IS" fullstop to match GraphQL spec

Co-authored-by: Benedikt Franke <[email protected]>

* Grammar (thanks @ghmcadams)

Co-authored-by: Gabriel McAdams <[email protected]>
Co-authored-by: Benedikt Franke <[email protected]>

Author: 3 people

INTERESTED_DEVELOPERS.md

@@ -11,11 +11,11 @@ involved with the following steps:
    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.
+   please reach out over Discord 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).
+   [GraphQL Foundation Discord community](https://discord.graphql.org) in the
+   #graphql-over-http channel.
 
 ## List of Developers
 

ROADMAP.md

@@ -15,11 +15,18 @@ client and server are compliant._
 
 ## 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.
+Version 1 aims to codify the most common existing uses of GraphQL queries and
+mutations over HTTP whilst encouraging some improved practices. The majority of
+GraphQL servers should find that they are already compatible with Version 1.0 of
+the GraphQL-over-HTTP specification, although they should still put work in to
+address the `SHOULD` behaviours that they may be missing, most notably around
+the use of the `application/graphql+json` Content-Type.
+
+Subscriptions, websockets and server-sent events are out of scope for version
+1.0.
+
+In layout and structure version 1.0 should lay a foundation for future
+development and standardization.
 
 ### Scope