Straw-man for new site architecture

[leebyron]

This is a straw-man outline for an improved version of graphql.org. The content on graphql.org has evolved only slightly since it was launched a year ago, and a lot has changed since then. In order to continue to serve its purpose as an education hub for GraphQL, it needs to improve both in design and content.

This document serves as a list of goals and (aggressive) timeframes for each section of the site along with a moderately detailed framing of the content for those pages. What is less captured by this document but equally important is a visual refresh that results in content that is easier to navigate and consume.

I'm sharing this here as a PR as an opportunity for folks to comment inline.

[lacker]

Maybe mention best practices for denial-of-service protection?

[leebyron]

Edits caused some of the discussion to be removed, but the discussion was good.

For posterity here's a link to a view that retains it: https://github.com/graphql/graphql.github.io/pull/35/files/cccb537c8d6a940684f752309050e226c444f4bb

[stubailo]

This isn't specifically about this outline, but do we have a great name for "Queries or mutations"? GraphQL-JS seems to call them "Documents". Is "Requests" the word we want to standardize on for this concept?

[leebyron]

To get all technical there are three concepts, but we should be pretty careful with our words. Agreed.

Document: a file containing GraphQL. The input to parse. (Sometimes we also call this Source 😕)

Operation: a query or mutation definition.

Request: asking GraphQL to execute a particular operation.

I think "Request" should be the most commonly used word when talking about things that have "Responses". Sometimes we say "query" for this concept, but request is more specific.

[leebyron]

Requests typically contain both operations and fragments (and come in the total form of a document)

[stubailo]

OK, so a request is something that contains:

• GraphQL document
  • Operation (at least one)
  • Fragments (zero or more)
• Variables
• Desired operation name (if there is more than one operation)

I think "Request" is a fine name for this, as long as we are careful to differentiate it from an HTTP request, which might include one or more GraphQL requests, in addition to headers and other HTTP-specific things.

Note: I think it might be OK for the purposes of this guide to basically assume that every GraphQL document you send to the server has exactly one operation, since that's how most implementations seem to work?

[lacker]

I think adding a new concept of a "graphql request" is confusing. Right now when people say "graphql request" they are generally referring to an HTTP request that contains some graphql. For example:

graphql/express-graphql#107
graphql-community/koa-graphql#64

Imagine trying to answer a question like "How can I stop my client from sending so many requests to my graphql server?" in a world where there are two separate concepts of "http request" and "graphql request".

A couple other confusing things about the concept:
1/ What about a root object and root context - would those also be considered part of the "graphql request"?
2/ There is no "GraphQLRequest" object in graphql.js, or in the other common graphql frameworks AFAIK.

I think it would be generally simpler to try to avoid using the word "request" and to try to just say "query" or "mutation".

[stubailo]

The issue with this is that GraphQL queries and mutations have so many (like 98%) concepts in common.

We really need a name for "the thing I can type into GraphiQL and hit send".

[lacker]

The issue with this is that GraphQL queries and mutations have so many (like 98%) concepts in common.

I don't object to using the word "operation" to mean "a query or a mutation". I object to the use of the word "request" to refer to a set of operations + fragments + some other stuff.

[stubailo]

Yeah it's just a bit awkward because there's a clear set of things you need to know about to send a GraphQL "request" or "query" or "operation" and get a result, which are not all part of the operation itself.

At the very least, this also includes variables and fragments.

[stubailo]

Should we merge this as a sign of agreement on the new outline?

[lacker]

Given that it's okay to just use curl/XHR/fetch, it might be nice to have inline code examples for how to call graphql servers with tabs for different languages, when we are giving examples for how to do it. Similar to the stripe API with curl/ruby/python/php/etc tabs https://stripe.com/docs/api

[stubailo]

It gets weird when you include Android and iOS, which are very annoying to do without some sort of code generation. People have voiced discontent with the JSON parsing capability of these languages. We're working on some tools, but they aren't ready yet.

[leebyron]

Agree w/ both of you. I think having inline examples for XHR/curl is an excellent idea, and we should do that. We should do what we can for iOS/Android, but we need to be careful to articulate that it may be too limiting an approach for those platforms because they suck so bad at network + json

[stubailo]

Yeah. I do agree that we should have a basic curl/jquery/fetch example.

[lacker]

It's kind of a shame that our story isn't cleaner here since iOS and Android have to be 2 of the top 3 client languages people are going to care about.

I accept that it's crappy. But, would you guys say that calling a GraphQL server on iOS and Android is worse than the situation for REST+JSON, or is it equally crappy, or do you not really know? If we don't tell people how then they are going to have to go trawl around the corners of internet to figure things out anyway.

[leebyron]

We should include iOS and android code. It's equally crappy to the REST story, it's more of an opportunity to mention why GraphQL clients exist.

The shame is that we don't have out of the box clients as good as Relay/Apollo for iOS/android yet

[leebyron]

See https://spring.io/guides/gs/consuming-rest-ios/ for how easy it is to turn 3 lines of JavaScript into a huge page for iOS.

[stubailo]

My understanding is that people using REST with iOS are either writing manual wrappers for their API that return typed objects, or using some sort of code generation solution. I'm not sure that using untyped raw JSON data is even feasible in those environments.

We have a proposal for what that might look like for GraphQL, which we have verified with a relatively wide range of devs: https://github.com/apollostack/apollo-ios

You can see what it looks like to hand-write the code for a simple query here: https://github.com/apollostack/apollo-ios/blob/0b44207d6b37f0960771e6198fec5e60f3c04891/StarWars/HeroNameQuery.swift

We're also starting on a code generation tool, to make all of this easier: https://github.com/apollostack/apollo-codegen

Our goal is to have a working solution for iOS in the short term, so maybe that will improve the situation.

[hramos]

Curious to hear more about the sentiment that JSON on iOS and Android is crappy.

For example, I don't agree with the idea that JSON parsing on iOS is annoying - it takes one line to do so with the built-in NSJSONSerialization class. Now, getting that JSON from a remote endpoint using the Foundation classes is not as simple, but this is mostly a solved problem thanks to libraries such as AFNetworking / Alamofire.

[lacker]

@hramos Well so if you were calling a JSON REST API from iOS would you have wrappers that turn things into objects, or would you just use the untyped json?

My suspicion is that most developers use untyped json and write the sort of quick n dirty code that gets the job done but leaves type-system aficionados aesthetically displeased ;-) If that's the case then we should just get some untyped json example code in the docs somewhere, ideally in a tabbish interface, to make it clear that you don't need a fancy client to get started with graphql - but the fancy clients just exist if you want to explore that direction.