r5

Author: lorensr

text/1.md

@@ -1,5 +1,7 @@
 # Chapter 1: Understanding GraphQL Through REST
 
+> Chapter 1 is a basic introduction to GraphQL through the eyes of the technology it’s replacing, REST. If you’re already sold on GraphQL and familiar with the basics, feel free to skip ahead to [Chapter 2: Query Language](2.md) for theory or [Chapter 5: Client Dev](5.md) and [Chapter 11: Server Dev](11.md) for coding.
+
 Chapter contents:
 
 * [Introduction](1.md#introduction)
@@ -27,12 +29,12 @@ Why use GraphQL? It turns out that GraphQL is amazingly useful—it combines a n
 - **Type-safe, self-documenting API:** GraphQL APIs are type-safe and self-documenting: the schema you define is exposed as interactive documentation for private or public consumption.
 - **No more API endpoint sprawl:** Backend engineers also love GraphQL. Once you write the code for accessing a data type, you won’t have to re-implement it. You don’t have to make a new endpoint for each view—you can leave that work up to the client and the GraphQL execution model, which is implemented by your GraphQL server library. And you don’t have to make a new API for each new app—you can have a single GraphQL API that covers all your business data.
 - **Query consolidation:** A request for multiple data types can be combined into a single query that is executed in parallel on the server.
-- **Static query analysis:** GraphQL schemas allow you to statically analyze the queries in your codebase and guarantee that you’ll never break them.
+- **Static query analysis:** GraphQL schemas allow you to statically analyze the queries in your codebase, and they guarantee that you’ll never break them.
 
 All together you end up with an API that is a delight to use and allows you to write expressive queries with understandable results:
 
 ![GraphiQL web interface](/img/graphiql.jpg)
-*A GraphQL query (left) and the results from the server (right) inside the [GraphiQL web interface](https://ch1.graphql.guide/graphql).*
+*A GraphQL query (left) and the results from the server (right) inside the GraphiQL (with an “i” and pronounced “graphical”) web interface, an easy-to-use IDE for developing GraphQL queries.*
 
 By reading this book, you’ll learn why you should use GraphQL in production and how to do it, and some best practices and common pitfalls. To start, we’ll dip our toes in the water: we’ll see the power of GraphQL through examples and answer the most obvious questions. Then we’ll dive deep into the intricacies of how this system was designed.
 
@@ -52,8 +54,12 @@ We recommend following along with the code, which can be found [on GitHub](https
 
 # A simple REST API server
 
+Background: [Node](bg.md#node-&-npm-&-nvm), [MongoDB](bg.md#mongodb), [HTTP](bg.md#http), [JSON](bg.md#json)
+
 We’ll start our process of understanding GraphQL by building a simple REST API using Node.js and the popular Express web framework. We’ll be retrieving data from a MongoDB database and using Mongoose as our object-relational mapping (ORM) to simplify querying the data we have stored.
 
+> Learn about MongoDB, the Node driver, and Mongoose in [Background > MongoDB](bg.md#mongodb).
+
 In this application, our server will listen for requests to the `/users/:id` URL. We use the ID passed as a parameter in the URL (as specified by the `:id`) to query a user record from the database and return it as a JSON string. If we encounter any errors, we return a 500 error, and if we can’t find the user, we return a 404—all standard REST practices.
 
 [`rest-server.js`](https://github.com/GraphQLGuide/graphql-rest-api-demo/blob/master/rest-server.js):
@@ -89,8 +95,6 @@ server.get('/users/:id', (req, res) => {
 
 // Start the application, listening on port 3000
 server.listen(3000)
-
-
 ```
 
 The Mongoose data models are stored in a separate file:
@@ -225,7 +229,7 @@ query {
 
 In addition to having a custom language for specifying the schema, GraphQL also has a language for specifying queries. This is more verbose than a REST API: with REST, the query is embedded in the URL itself; in GraphQL, we specify the endpoint that we’re calling (`user`) along with the argument (`id` with a value of `"123"`), and we also list every `User` field we want the server to return. This extra syntax is what makes GraphQL so flexible and explicit: it gives us an exact list of the data we are attempting to fetch.
 
-We have a couple options if we want to run this query and get the data back from the server. To start, let’s use the command line to show how a typical query might be executed:
+We have a couple of options if we want to run this query and get the data back from the server. To start, let’s use the command line to show how a typical query might be executed:
 
 ```sh
 $ curl -X POST -H "Content-Type:application/json" \
@@ -246,14 +250,14 @@ $ curl -X POST -H "Content-Type:application/json" \
 ```
 No, in fact! Every time we query a GraphQL endpoint, we get a valid JSON response. In this case `"user"` is `null`, as its value wasn’t able to be determined. This becomes very useful when we handle permissions and errors, which we’ll get into [later](#security-&-error-handling).
 
-When we run our server (`node graphql-server.js`) and visit [localhost:3000/graphql](http://localhost:3000/graphql) in the browser, we see the fantastic, easy-to-use web interface called GraphiQL (with an “i” and pronounced “graphical”):
+When we run our server (`node graphql-server.js`) and visit [localhost:3000/graphql](http://localhost:3000/graphql) in the browser, we see GraphiQL::
 
 ![GraphiQL web interface](/img/graphiql.jpg)
 *The results returned from a query inside the GraphiQL web interface.*
 
 > You can also try out a hosted version here: [ch1.graphql.guide/graphql](https://ch1.graphql.guide/graphql)
 
-Seeing or using GraphiQL for the first time is often the moment that software engineers become GraphQL converts.  It offers an an intuitive interface to read the documentation for and query a GraphQL schema. We can write a query, see the results returned from the server, and explore the documentation on the right that’s been automatically generated from the schema. This is something that REST can’t replicate without a ton of extra work or an additional framework. GraphQL is only just starting to pay off, though—we’ll see that as the REST API becomes more and more complex, the complexity of the equivalent GraphQL API remains the same.
+Seeing or using GraphiQL for the first time is often the moment that software engineers become GraphQL converts.  It offers an an intuitive interface to read the documentation for and query a GraphQL schema. We can write a query, see the results returned from the server, and explore the documentation on the right that’s been automatically generated from the schema. This is something that REST can’t replicate without a ton of extra work or an additional framework. GraphQL is only just starting to pay off, though—as the REST API becomes more and more complex, the complexity of the equivalent GraphQL API remains the same.
 
 # Querying a set of data
 
@@ -805,6 +809,6 @@ In a modern application, the consumer needs to be in control of what data they c
 
 While GraphQL has a number of new concepts to learn (GraphQL schemas, the query language, etc.), these features are designed to help us write our applications correctly from the start—whereas the prospect of building a comparable REST API can be absolutely overwhelming in its complexity.
 
-GraphQL truly is the most developer-friendly way of building an API. It puts the consumer in full control of the data requested, and as such we avoid querying data that we don’t need. As an added bonus, there is clear, automatically-generated documentation we can browse to understand any new GraphQL API.
+GraphQL truly is the most developer-friendly way of building an API. It puts the consumer in full control of the data requested, and we can therefore avoid querying data that we don’t need. As an added bonus, there is clear, automatically-generated documentation we can browse to understand any new GraphQL API.
 
 The developers of GraphQL learned from REST’s challenges and mistakes over the years, and have turned the best parts into a streamlined interface that will surely be the standard for API design for many years to come. The rest of this book will dive deep into the benefits of GraphQL, how to implement it efficiently, and how to build the best applications using this technology.