Straw-man for new site architecture #35
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,180 @@ | ||
| # New GraphQL.org Site Architecture: | ||
|
|
||
| ## Index | ||
|
|
||
| *Goal:* This is the landing page and is our opportunity to quickly capture attention and explain what GraphQL is and why you should care. | ||
|
|
||
| *Timeframe:* Launch Mon, Sept 12th | ||
|
|
||
| This page is effectively a marketing page for GraphQL and should be the visual, scrollable version of the "Introducing GraphQL" conference talks and should be rich with visual metaphor and illustration and take advantage of whitespace to make individual salient points. | ||
|
|
||
| Above the fold, this page should succinctly explain what GraphQL is and illustrate with a simple (editable) query/response example. Before scrolling you should understand the following: | ||
|
|
||
| * GraphQL solves the same problem as REST. | ||
| * GraphQL is an query language for APIs (and not Databases). | ||
| * GraphQL is sent by client applications, such as an iOS app. | ||
| * GraphQL is evaluated by a web service and often returned as JSON. | ||
| * GraphQL services provide a complete description of your data with a type system. | ||
| * It's easy to build powerful tools for your data using GraphQL. | ||
|
|
||
| Below the fold we should introduce concepts one at a time, each with visual metaphor and take-aways: | ||
|
|
||
| 1) GraphQL clients describe what they need in terms of how client developers think about data. | ||
|
|
||
| * If you're familiar with JSON, GraphQL is easy to learn and understand. | ||
| * GraphQL only sends what you ask for, nothing more or less, making your app faster and more stable. | ||
| * It's easy to anticipate the shape of the result of any query. | ||
|
|
||
| 2) GraphQL queries can access many "resources" in a single network request. | ||
|
|
||
| * A query can access properties of not just one object, but of many related objects. | ||
|
There was a problem hiding this comment. It's also built in that you can "batch" multiple requests into one request. REST doesn't support batching, GraphQL does. There was a problem hiding this comment. Unfortunately, it's not "built-in" in any of the open source server implementations we found - you need to write a custom network layer on top of the graphql execution engine to get batching, which is something you could just as easily do with REST. I agree that it would be awesome if this were a benefit of GraphQL but it's not quite there yet as an out-of-the-box feature. There was a problem hiding this comment. This is a muddied point unfortunately because of legacy GraphQL and Relay encoding those legacy assumptions in how it works. Maybe we just avoid the word "batch". To clarify, GraphQL does not support batching network requests (GraphQL also doesn't concern itself with what a network is). GraphQL does support multiple top level fields in a single query (Relay does not yet support this, unfortunately). I agree with @lacker that a take away should be that multiple root fields allows for accessing multiple unrelated values simultaneously in a single query. There was a problem hiding this comment. To me, batching means "these two requests can be automatically grouped into one request". So I agree we should instead talk about how you can fetch as many resources as you want in one request. |
||
| * A query can access multiple unrelated objects at once. | ||
| * Compared to REST, GraphQL collects all the data needed for your app with much less network activity, making your app faster. | ||
|
|
||
| 3) GraphQL services describes what's possible with a strong type system. | ||
|
|
||
| * GraphQL services provide a complete description of your data. | ||
| * Every `{ }` corresponds to an object of a particular type, and every type describes the fields available. | ||
| * GraphQL only runs queries that make sense and provides helpful error messages. | ||
| * Tools and IDEs can make editing queries easy via type-aheads. | ||
| * GraphiQL is a free tool that you can use. | ||
| * Type system defines descriptions, making it easy to keep documentation up to date. | ||
| * Every query guarantees the shape and type of its response. | ||
|
|
||
| 4) GraphQL is composable via fragments. | ||
|
|
||
| * Fragments describe a portion of some Type to be queried. | ||
| * Fragments are often used next to View code where data is used. | ||
| * Fragments are composed together to create full queries. | ||
|
|
||
| 5) GraphQL makes backwards-compatible APIs easy. | ||
|
|
||
| * Server does not need to worry about concerns of any particular client, only the complete set of capabilities. Clients are responsible for the data they receive. | ||
| * Because GraphQL only sends what you ask for, new capabilities can be introduced via new fields on types with no impact on existing queries. | ||
| * Old capabilities can be marked "deprecated" with no impact on existing queries. | ||
| * No versioning your API when using GraphQL leads to cleaner code on the server. | ||
|
|
||
| 6) GraphQL queries are answered by simple functions on your server. | ||
|
There was a problem hiding this comment. This could be a very important point to make earlier, to head off people asking questions like "what databases are supported by GraphQL?" There was a problem hiding this comment. Yeah, we should allude to this in the above-the-fold - it should be clear before you start scrolling that GraphQL is for building APIs not for talking to Databases. This section will build on the above few sections to make that point with visual metaphor and more detail. |
||
|
|
||
| * GraphQL is not backed by any database technology, just like REST. | ||
| * Every field on each type is represented by a function for retrieving that data. | ||
| * GraphQL will call your functions and execute a query with optimal concurrency. | ||
| * It's easy to write a GraphQL API using your existing data model. | ||
|
|
||
| Finally, there will be a set of links for learning more (diving into `Learn`) and for getting started (in `Code`). As well as a wall-o-logo for companies using GraphQL. | ||
|
|
||
| ## Learn | ||
|
|
||
| *Goal:* Introduce GraphQL, one concept at a time, covering both primary concepts and best practices. | ||
|
|
||
| *Timeframe:* Basic primary concepts by Sept 12th, advanced primary concepts by Sept 30th, best practices as ready over Q3/Q4. | ||
|
|
||
| Where "GraphQL the Spec" is designed for a specific audience of those building GraphQL servers, this represents "GraphQL the Book" and is designed for the audience of anyone who wishes to use GraphQL. It should cover both GraphQL core concepts in addition to best practices and further topics, and it should range from introductory concepts through advanced concepts. | ||
|
There was a problem hiding this comment. Do you think this part will just be stuff you read, or can we make it interactive in some way? There was a problem hiding this comment. I'm going to optimize for time here and suggest that at least for our initial relaunch, that this is static read content. However we already have built a "mini GraphiQL" component we can recycle that allows for live editing of GraphQL examples. I'm open to ideas about more interactivity if you've got em. |
||
|
|
||
| The landing page for this section should begin as a more information-rich introduction to GraphQL, explaining why you might use it, and give a brief overview of the constituent parts. Take-aways from this introduction page: | ||
|
|
||
| * GraphQL is a query language. | ||
| * GraphQL servers describe a type system, called a "schema". | ||
| * Clients can access a GraphQL server's type system to learn about what's possible. | ||
| * Clients send queries to servers and typically get back JSON. | ||
| * GraphQL servers validate and execute GraphQL queries. | ||
|
|
||
| There is then a TOC through the sections and chapters (this is a straw-man list, open to reordering and addition) | ||
|
|
||
| * Introducing GraphQL (this initial page) | ||
| * Core Concepts: | ||
| * Requests: | ||
|
There was a problem hiding this comment. 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? There was a problem hiding this comment. 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. There was a problem hiding this comment. Requests typically contain both operations and fragments (and come in the total form of a document) There was a problem hiding this comment. OK, so a request is something that contains:
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? There was a problem hiding this comment. 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 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: I think it would be generally simpler to try to avoid using the word "request" and to try to just say "query" or "mutation". There was a problem hiding this comment. 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". There was a problem hiding this comment.
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. There was a problem hiding this comment. 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. |
||
| * Basics (queries & mutations, fields, arguments, aliases, comments) | ||
| * Variables | ||
| * Fragments | ||
| * Values | ||
| * Directives (skip & include) | ||
| * Type System: | ||
|
There was a problem hiding this comment. When we wrote a lot of this content at http://docs.apollostack.com/graphql/, (which we would be happy to donate and expand on here) we found that it was hard to explain queries without explaining what they are querying. So it might be a good idea to put the schema/type system up front, and queries second, because queries are more easily explained in terms of the types they query (for example, conditional fragments don't make much sense if you don't know about interfaces or union types) There was a problem hiding this comment. Yeah, I agree with this. I think the basics you need for pretty much any API are: The schema language with scalar types, object types, and lists You can build a small application like a todo list using just those. I don't think you can get by without any of them, though. So I would suggest putting those first under "the basics" and considering other stuff to be "advanced". There was a problem hiding this comment. Technically you can build a todo list without auth, and GraphQL doesn't actually solve that for you at all. So IMO queries and mutations are the only really "basic" concepts. But aliases and fragments are a close second, especially because aliases are critical for querying the same field twice with different arguments. There was a problem hiding this comment. I don't know that I agree with flipping these sections, but I see your point. I think the same point could be made in reverse that spending a whole section introducing the intricacies of the type system before you know how to write a query can seem overwhelming and lead to the idea that GraphQL is too complicated. If I had to write a book about SQL, I definitely would not start Chapter 1 explaining the possible column types, I would start with SELECT. I think it's important for Chapter 1 to effectively cover: "My codebase has GraphQL in it, and I might need to edit or write it, what do I do?" Right now I've proposed two sections - one on understanding queries, and one on understanding the type system, however you're definitely right to point out that there are knowledge dependencies between them. What do you think about interleaving these sections together, sorting roughly by pre-req? This way we can introduce interfaces and unions before introducing inline fragments, for example. There was a problem hiding this comment. I'd argue that before you introduce SELECT, you need to introduce the concept of rows and columns. Perhaps it's like:
Then we can recommend reading both "basic" sections before the advanced ones? Perhaps this means in addition to having the guide, we need an "intro to graphql" article that we expect people to read before they dive into the guide? There was a problem hiding this comment.
Yeah absolutely, see L69-77. The landing page for "Learn" is effectively this "Chapter 0" intro which is a nuts-to-bolts overview. If you only read this one page, you'll get a good handling on all the critical core concepts necessary to feel competent in a discussion about GraphQL and to have context to understand further sections. There was a problem hiding this comment. This is part of why I'm not that worried about the careful ordering of introducing these. It's just as crazy to say "Let's learn about every detail of the query language before talking about the type system" as it is to say "Let's learn about every detail of the type system before talking about the query language". We absolutely have to have an introduction that describes both in context of one another. There was a problem hiding this comment. You can't build a todo list app without auth - how do you prevent other people from seeing your todo items, or a single user from deleting all the todo items? There was a problem hiding this comment. I would agree that it's important if GraphQL had a built-in answer for auth, but it doesn't. Any auth-related concerns would need to dive into transport and impementation-specific details, which should live somewhere else in my opinion. We just need to make it clear that auth is possible, but that GraphQL intentionally doesn't have an opinion about how you do it. If GraphQL is going to become a widely-adopted standard, it's important that we make a clear distinction between the standard/spec itself and everything else that is up to the implementer, even if it's something that you would unquestionably need in a production app (for example, rate limiting). There was a problem hiding this comment. Right. The GraphQL spec is intentional in the limited scope it describes to intentionally provide for options for all the other details of running a production web service (including the most important option: "the thing we're already using"). We still should provide best practices about a lot of these topics and make this clear. |
||
| * Basics (Schema, Objects & Fields) | ||
| * Scalars & Enums | ||
| * Lists & NonNull (mention error handling) | ||
| * Interfaces & Unions | ||
| * How GraphQL Works: | ||
| * Validation | ||
| * Execution & Error Handling | ||
| * Introspection | ||
| * Best Practices: | ||
|
There was a problem hiding this comment. Maybe mention best practices for denial-of-service protection? |
||
| * Servers: | ||
| * Serving over HTTP | ||
| * Authentication & Authorization | ||
| * Mutations | ||
| * Paginating Lists | ||
| * Schema Changes & Versioning | ||
| * Query Performance (Batching & Caching) | ||
| * Security & Rate Limiting | ||
| * Schema Design Guidelines | ||
| * Clients: | ||
| * Using Variables | ||
| * Co-locating Fragments | ||
| * Caching Results | ||
| * Persisted Queries | ||
| * Generating Models | ||
| * Migrating from REST | ||
|
|
||
| ## Code | ||
|
|
||
| *Goal:* Introduce open source GraphQL tools along with quick getting started guidelines for each. | ||
|
|
||
| *Timeframe:* At least 3 servers described by Sept 12th, remainder by Sept 30th. | ||
|
|
||
| This page is all about fulfilling the "Ok I'm sold! Now what?" conundrum. It should first very quickly reintroduce the elements of GraphQL you would expect to see software for as well as offer a quick path towards getting something working. | ||
|
|
||
| 1) Servers | ||
|
|
||
| Explain the purpose of a GraphQL server, that there are servers written for many different languages and environments, and that graphql-js is the reference implementation operated by Facebook. | ||
|
There was a problem hiding this comment. Right now setting up a server with graphql-js and express-graphql is also covered by the same graphql.org website. Also the API reference for graphql-js. Is that information architecture ok with you? I prefer it that way (how it is now) because it's annoying to create more websites. There was a problem hiding this comment. I find that it's very demotivating when you are trying to build a GraphQL server, and there's one that seems extremely official because it's on the main website. Unless we expect everyone using GraphQL with JavaScript to use express-graphql (which isn't possible partially because not everyone is using express), I think it's best to keep the documentation somewhere else. There's also the side-effect of making people think that GraphQL as a technology is tied to JavaScript, which it definitely isn't, even at Facebook. There was a problem hiding this comment. I think we can be clear that it is just "the reference implementation" and that there are many other ways to stand up a GraphQL server. For information architecture I suggest keeping it how it is now on the left hand bar, with the bottom section being things that just relate to "the reference implementation" rather than to graphql in general. There was a problem hiding this comment. I would prefer the API references for our packages live elsewhere, though we can definitely make the URLs reasonable. There are a few reasons for this:
There was a problem hiding this comment. I think I would agree with @lacker and @stubailo on this one. On one hand, it would be nice not to give any particular implementation "premium" status since it can be discouraging, but on the other hand it always helpful and encouraging to immediately see something real: real code that does something useful and gives the reader feeling: "This looks simple enough, I can do it too!". The thing is, the landing page and some other pages contain a lot of abstract concepts and many of these concepts would be new to the reader. Giving too much theory in one big chunk may cause fatigue, even if these concepts are very interesting. That's why I always in favor of balancing theory and abstract concepts with something very concrete and down-to-earth. This this case concrete implementation of these concepts could be the javascript/java/ruby/scala/etc... code. I think maybe we can get some inspiration from MessagePack landing page. When I first saw this page for the first time, it immediately gave impression that:
One issue with MessagePack page is lack of polish, in my opinion. I I think this raises a bigger question: if we include some examples in different languages then ideally they should:
I really like what @steveluscher did with zero-to-graphql. It provides implementation of the same GraphQL schema in different languages. All of these examples are implementing very similar application with same architecture - it's a web application that serves JSON over HTTP and uses an SQL database to store the data. The schema itself is very minimal but still able to demonstrate a lot of concepts (like many-to-many relationships). Maybe we can expand on this idea and make it "official"/supported part of the ecosystem? If there is interest of library maintainers and the schema/application is small enough to make it easy to maintain, then maybe it can work. I feel that at this point it does not matter whether it is embedded in the graphql.org or maintained somewhere externally (e.g. on the github as a monorepo or a a set of independent repositories). It's more the learning experience and some quality/uniformity standard for these examples that do matter. |
||
|
|
||
| Each server should contain the following: | ||
| * Logo | ||
| * Name of Project | ||
| * Language/Environment | ||
| * Link to website | ||
| * Getting started (e.g. npm install + code sample) | ||
|
|
||
| 2) Clients | ||
|
|
||
| Explain the purpose of a GraphQL client, that it's okay to just use curl/XHR/fetch, and that clients can offer more value via smart caches and integration with UI frameworks. | ||
|
There was a problem hiding this comment. 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 There was a problem hiding this comment. 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. There was a problem hiding this comment. 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 There was a problem hiding this comment. Yeah. I do agree that we should have a basic curl/jquery/fetch example. There was a problem hiding this comment. 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. There was a problem hiding this comment. 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 There was a problem hiding this comment. 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. There was a problem hiding this comment. 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. There was a problem hiding this comment. 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 There was a problem hiding this comment. @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. |
||
|
|
||
| Each client should contain similar set of info as servers. | ||
|
|
||
| 3) Services | ||
|
|
||
| Hosted GraphQL-as-a-service have an opportunity to pitch themselves here. | ||
|
|
||
| 4) Tools | ||
|
|
||
| Common tools used by GraphQL community, e.g. GraphiQL. | ||
|
|
||
| ## Community | ||
|
|
||
| *Goal:* Central dispatch for finding help for GraphQL questions, learning about conferences and meetups, and connecting with the community. | ||
|
|
||
| *Timeframe:* Simple version by Sept 12th, evolve over time. | ||
|
|
||
| This page should serve as a high-level view of what resources are available and what's going on in the community. It should encourage pull-requests to facilitate being updated by the community over time. | ||
|
|
||
| * Links out to: | ||
| * Stack Overflow topic | ||
| * Slack/Discord channels | ||
| * Popular blogs | ||
| * Twitter feed | ||
|
There was a problem hiding this comment. Should we add "Future of GraphQL" or "Roadmap" to this list? There was a problem hiding this comment. I'm a bit worried about this because there isn't a clear path for how these roadmap items will be designed and developed. Since there are a lot of GraphQL tools and implementations out there, having a very forward looking roadmap could cause confusion about what is and isn't part of GraphQL, or what these implementations should be supporting. There was a problem hiding this comment. I think that's a valid concern. What are some alternatives to help us keep the GraphQL community cohesive? There was a problem hiding this comment. I agree - I think we should address future/roadmap separately. It's potentially confusing to see roadmap in the context of a general technology, instead we would expect to see roadmaps relative to spec or individual GH repos. For now I think it's safe to punt on this, it's not critical to cover but I agree that we should eventually find a better way to communicate future plans. Maybe posts on the blog could be a way to start this. There was a problem hiding this comment.
I guess this was one point of confusion before - GraphQL subscriptions originated as part of a blog post, but never really got added to the spec or reference implementation in a meaningful way. Now that this feature is being added to some of the community implementations, it will be interesting to see how it develops. |
||
| * Calendar of upcoming meetups or conference talks related to GraphQL (encourage edits by community) | ||
| * Grid of recorded videos about GraphQL (conf talks, etc). | ||
|
|
||
| ## Blog | ||
|
|
||
| *Goal:* GraphQL core team's blog, signal-boosting popular articles written elsewhere. | ||
|
|
||
| While any evergreen content typically belongs as chapters in the "Learn" section, the Blog is an opportunity for GraphQL core team members or occasional invited contributors to discuss experiments, interesting applications, or signal-boost things like new releases of the GraphQL spec, the reference implementation, upcoming events, or links out to interesting articles. | ||
|
|
||
| Task: generate RSS feed (maybe also email subscription?) | ||
|
|
||
| Long term goal: metric frequency of posts, set goals to moderate frequency. | ||
|
|
||
| ## Spec | ||
|
|
||
| Link out to GraphQL spec. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When talking to developers currently using and also looking into GraphQL, the main benefit for them was that it presents an API layer organized in terms of objects, types, and fields, rather than endpoints. So it might be worth moving "GraphQL services provide a type system." to the front, and emphasize that it:
I think those two resonated the most with people we talked to.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I especially like the point about avoiding multiple endpoints (simpler).
Each of these points should be concise, visual, and quickly consumed (and all below the fold), so my concern in ordering these sections is to start with the most striking and simple to explain properties of GraphQL and then to build atop those. It's hard to explain why the type system is valuable without first explaining these first two points.
But if the type system is critical enough that it should be conveyed ASAP on this page, then perhaps it should be a goal for the above-the-fold to convey this point. I think that's actually quite reasonable.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
From my perspective, the type system is absolutely the main thing. We're basically starting all of our conversations at this point with "GraphQL gives you a complete description of the data in your API layer, a great way to query it, and a way to build awesome developer tools on top of it."
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I like that framing.
I think the perspective on the ordering of these depends a lot on if you're coming with the perspective of a server or client. The type system is a BFD for servers, but for clients the query language is the BFD. Ultimately of course both are BFDs :). The challenge is introducing these concepts to get an "aha!" asap.