From 761ff92bb8c3c5613f616cd7da45bc082d32ad3f Mon Sep 17 00:00:00 2001 From: Jesse Rosenberger Date: Mon, 30 Apr 2018 15:36:08 -0700 Subject: [PATCH] docs: Iteration from Docs workshop. * Bury Best Practices, for the time being. * Bury Schema, but leave it on disk. * Introduce new Querying section. * Move "Why Apollo Server?" into "Index". * ...to be refined. * Remove no-longer-helpful "Getting Started" from "Index". cc @stubailo @evans @peggyrayzis @JakeDawkins @unicodeveloper @jbaxleyiii --- docs/_config.yml | 14 +--------- docs/source/essentials/data.md | 2 +- docs/source/essentials/querying.md | 45 ++++++++++++++++++++++++++++++ docs/source/essentials/schema.md | 45 ++---------------------------- docs/source/essentials/server.md | 2 +- docs/source/index.md | 36 ++---------------------- 6 files changed, 53 insertions(+), 91 deletions(-) create mode 100644 docs/source/essentials/querying.md diff --git a/docs/_config.yml b/docs/_config.yml index 9585735d..a9db16cf 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -8,25 +8,13 @@ versions: sidebar_categories: null: - index - - why-apollo-server - getting-started - whats-new Essentials: - essentials/schema - essentials/server - essentials/data - Schema: - - schemas/organization - - schemas/types - - schemas/resolvers - - schemas/directives - Best Practices: - - best-practices/authentication - - best-practices/schema-design - - best-practices/performance - - best-practices/security - - best-practices/caching - - best-practices/monitoring + - essentials/querying Deployment: - deployment/index - deployment/heroku diff --git a/docs/source/essentials/data.md b/docs/source/essentials/data.md index 8ae0be19..e69cfd22 100644 --- a/docs/source/essentials/data.md +++ b/docs/source/essentials/data.md @@ -1,5 +1,5 @@ --- -title: Fetching data +title: Fetching data with resolvers --- ## Overview diff --git a/docs/source/essentials/querying.md b/docs/source/essentials/querying.md new file mode 100644 index 00000000..03e9194b --- /dev/null +++ b/docs/source/essentials/querying.md @@ -0,0 +1,45 @@ +--- +title: Sending queries +--- + +## Operation names + +When sending the queries and mutations in the above examples, we've used either `query { ... }` or `mutation { ... }` respectively. While this is fine, and particularly convenient when running queries by hand, it makes sense to name the operation in order to quickly identify operations during debugging or to aggregate similar operations together for application performance metrics, for example, when using [Apollo Engine]() to monitor an API. + +Operations can be named by placing an identifier after the `query` or `mutation` keyword, as we've done with `HomeBookListing` here: + +```graphql +query HomeBookListing { + getBooks { + title + } +} +``` + +## Variables + +In the examples above, we've used static strings as values for both queries and mutations. This is a great shortcut when running "one-off" operations, but GraphQL also provides the ability to pass variables as arguments and avoid the need for clients to dynamically manipulate operations at run-time. + +By defining a map of variables on the root `query` or `mutation` operation, which are sent from the client, variables can be used (and re-used) within the types and fields themselves. + +For example, with a slight change to the mutation we used in the previous step, we enable the client to pass `title` and `author` variables alongside the operation itself. We can also provide defaults for those variables for when they aren't explicitly set: + +```graphql +mutation HomeQuickAddBook($title: String, $author: String = "Anonymous") { + addBook(title: $title, author: $author) { + title + } +} +``` + +GraphQL clients, like [Apollo Client](https://www.apollographql.com/docs/react/), take care of sending the variables to the server separate from the operation itself: + +```json +{ + "query": "...", + "variables": { "title": "Green Eggs and Ham", "author": "Dr. Seuss" } +} +``` + +This functionality is also supported by tools like GraphQL Playground and GraphiQL. + diff --git a/docs/source/essentials/schema.md b/docs/source/essentials/schema.md index ea1439b3..650ba666 100644 --- a/docs/source/essentials/schema.md +++ b/docs/source/essentials/schema.md @@ -1,6 +1,6 @@ --- -title: Building a GraphQL schema -sidebar_title: Building a schema +title: Understanding schema concepts +sidebar_title: Schema concepts --- ## Overview @@ -203,47 +203,6 @@ type Query { This makes SDL-generation even easier since many GraphQL tools auto-complete field names, along with the descriptions, when available. -## Operation names - -When sending the queries and mutations in the above examples, we've used either `query { ... }` or `mutation { ... }` respectively. While this is fine, and particularly convenient when running queries by hand, it makes sense to name the operation in order to quickly identify operations during debugging or to aggregate similar operations together for application performance metrics, for example, when using [Apollo Engine]() to monitor an API. - -Operations can be named by placing an identifier after the `query` or `mutation` keyword, as we've done with `HomeBookListing` here: - -```graphql -query HomeBookListing { - getBooks { - title - } -} -``` - -## Variables - -In the examples above, we've used static strings as values for both queries and mutations. This is a great shortcut when running "one-off" operations, but GraphQL also provides the ability to pass variables as arguments and avoid the need for clients to dynamically manipulate operations at run-time. - -By defining a map of variables on the root `query` or `mutation` operation, which are sent from the client, variables can be used (and re-used) within the types and fields themselves. - -For example, with a slight change to the mutation we used in the previous step, we enable the client to pass `title` and `author` variables alongside the operation itself. We can also provide defaults for those variables for when they aren't explicitly set: - -```graphql -mutation HomeQuickAddBook($title: String, $author: String = "Anonymous") { - addBook(title: $title, author: $author) { - title - } -} -``` - -GraphQL clients, like [Apollo Client](https://www.apollographql.com/docs/react/), take care of sending the variables to the server separate from the operation itself: - -```json -{ - "query": "...", - "variables": { "title": "Green Eggs and Ham", "author": "Dr. Seuss" } -} -``` - -This functionality is also supported by tools like GraphQL Playground and GraphiQL. - ## Next steps At this point, we hope to have explained the basic information necessary to understand a GraphQL schema. diff --git a/docs/source/essentials/server.md b/docs/source/essentials/server.md index 90f4f21c..88f00af9 100644 --- a/docs/source/essentials/server.md +++ b/docs/source/essentials/server.md @@ -1,5 +1,5 @@ --- -title: Running a server +title: Building a server --- ## Overview diff --git a/docs/source/index.md b/docs/source/index.md index 0482c7a0..e704a7fd 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -3,10 +3,13 @@ title: Introduction description: What is Apollo Server and what does it do? --- +## Why GraphQL? Why Apollo Server? + Apollo Server is the best way to build a production ready GraphQL server. It is designed from day one to make it easy to connect data from your backend(s) to a well designed schema ready for clients to use! Apollo Server is designed to work with every major Node HTTP servers such as Express, Hapi, and Koa, as well as serverless environments like AWS Lambda. Apollo Server supports the entire GraphQL Spec and can be queried from any GraphQL client. It's: + 1. **Incrementally adoptable**, so you can drop it into an existing app today. 2. **Universally compatible**, so it works with any build setup, any GraphQL client, and any data source. 3. **Simple to get started with**, so you can start loading data right away and learn about advanced features later. @@ -15,39 +18,6 @@ Apollo Server supports the entire GraphQL Spec and can be queried from any Graph These docs will help you go from getting started with Apollo to becoming an expert in no time! -## Overview - -This documentation aims to provide a complete guide of how to build a GraphQL server by providing easy-to-understand overviews, in-depth guides and comprehensive best-practices. - -The documentation is organized with basic concepts and design decisions first and more advanced topics later on. Each section lists prerequisites needed to get the most out of it. - -After finishing, you will know: - -* Basic GraphQL concepts, in the server context -* Why GraphQL is effective on the server -* What requests a GraphQL server will receive - * Queries - * Mutations - * Advanced subscriptions -* How a GraphQL server defines an API and creates responses to those requests -* Best practices for designing a server - * Authentication - * Schema design - * etc. - -## Getting Started - -The docs for Apollo Server are mainly written using the [Express integration](./servers/express.html), but most of the examples work no matter what server library you use. The docs are broken into six distinct sections to make it easy to find your way around: - -1. **Essentials**, which outlines everything you need to know in order to get started quickly -2. **Schema Development**, which goes over what a GraphQL schema is, and how to write one -3. **Running a Server**, which explains the mechanics of exposing your schema to clients -4. **Best Practices**, to explain the best possible way to build a GraphQL service -5. **Working with Backends**, so you can work with the data you have right away -6. **API**, to act as an entry point to find API details for key server libraries - -Getting started is as simple as installing a few libraries from npm! [Getting started](./getting-started.html) is a good place to start your adventure with Apollo Server! - ## Productive GraphQL Development Apollo Server, and the rest of the Apollo ecosystem, give you a powerful set of tools to rapidly stand up a GraphQL API on top of your existing, or new, backends. It does this by focusing on a schema-first approach where you build your schema with a concise, declarative syntax, and fill in the logic with data fetching resolver functions. It is easy to get started with [one-step mocking]() while you fill out your data and build your UI. With powerful tools like [schema directives](./schemas/directives.html), [tracing and cache control](./best-practices/caching.html), and [schema stitching](), you can build the service of your dreams without writing a line of code more than you need.