PR feedback

Author: andimarek

content/blog/getting-started-with-spring-boot.md

@@ -7,14 +7,14 @@ date = 2019-01-23
 toc = "true"
 +++
 
-This is a tutorial for people who never development a GraphQL server with Java. Some Spring Boot and Java knowledge is required. While we give a brief introduction into GraphQL the focus of this tutorial is on developing a GraphQL server in Java.
+This is a tutorial for people who never development a GraphQL server with Java. Some Spring Boot and Java knowledge is required. While we give a brief introduction into GraphQL, the focus of this tutorial is on developing a GraphQL server in Java.
 
 
 # GraphQL in 3 minutes
 
 GraphQL is a query language to retrieve data from a server. It is an alternative to REST, SOAP or gRPC in some way. 
 
-For example we wanna query the details for specific book from a online store backend.
+For example, we wanna query the details for specific book from a online store backend.
 
 With GraphQL you send the following query to server to get the details for the book with the id "123":
 
@@ -32,9 +32,13 @@ With GraphQL you send the following query to server to get the details for the b
 }
 {{< / highlight >}}
 
-This is not JSON (even if it looks remotely similar), it is a GraphQL query.
+This is not JSON (even if it looks remotely similar), it is a GraphQL query. 
+It basically says:
+- query a book with a specific id
+- get me the id, name, pageCount and author from that book
+- for the author I want to know the firstName and lastName
 
-But the response is normal JSON:
+The response is normal JSON:
 {{< highlight json "linenos=table" >}}
 { 
   "bookById":
@@ -50,7 +54,7 @@ But the response is normal JSON:
 }
 {{< / highlight >}}
 
-One very important property of GraphQL is that it is statically typed: the server knows exactly of the shape of every object you can query and any client can actually "inspect" the server and ask for the so called "schema". The schema describes what queries are possible and what fields you can get back. 
+One very important property of GraphQL is that it is statically typed: the server knows exactly of the shape of every object you can query and any client can actually "inspect" the server and ask for the so called "schema". The schema describes what queries are possible and what fields you can get back. (Note: when we refer to schema here, we always refer to a "GraphQL Schema", which is not related to other schemas like "JSON Schema") 
 
 The schema for the above query looks like this:
 
@@ -73,7 +77,7 @@ type Author {
 }
 {{< / highlight >}}
 
-This tutorial will focus on how to implement a GraphQL server with schema in Java.
+This tutorial will focus on how to implement a GraphQL server with exactly this schema in Java.
 
 We barely touched GraphQL. Further information can be found on the official page: https://graphql.github.io/learn/
 
@@ -82,7 +86,7 @@ We barely touched GraphQL. Further information can be found on the official page
 [GraphQL Java](https://www.graphql-java.com) is the Java (server) implementation for GraphQL. 
 The are several repositories in the GraphQL Java Github org. The most important one is the [GraphQL Java Engine](https://github.com/graphql-java/graphql-java) which is basis for everything else.
 
-GraphQL Java Engine itself is only concerned with executing queries. It doesn't deal with any HTTP or JSON related topics. For these aspects we will use the [GraphQL Java Spring Boot](https://github.com/graphql-java/graphql-java-spring) adapter which takes care of exposing our API via Spring Boot over HTTP.
+GraphQL Java Engine itself is only concerned with executing queries. It doesn't deal with any HTTP or JSON related topics. For these aspects, we will use the [GraphQL Java Spring Boot](https://github.com/graphql-java/graphql-java-spring) adapter which takes care of exposing our API via Spring Boot over HTTP.
 
 The main steps of creating a GraphQL Java server are:
 
@@ -96,7 +100,7 @@ This is in no way a comprehensive API, but it is enough for this tutorial.
 
 # Create a Spring Boot app
 
-The easiest way to create a Spring Boot app is to use the initializr at https://start.spring.io/.
+The easiest way to create a Spring Boot app is to use the "Spring Initializr" at https://start.spring.io/.
 
 Select: 
 
@@ -109,7 +113,7 @@ For the project metadata we use:
 - Group: `com.graphql-java.tutorial`
 - Artifact: `book-details`
 
-As dependency we just select `Web`.
+As dependency, we just select `Web`.
 
 A click on `Generate Project` will give you a ready to use Spring Boot app.
 All subsequently mentioned files and paths will be relative to this generated project.
@@ -154,16 +158,16 @@ type Author {
 {{< / highlight >}}
 <p/>
 
-This schema defines one top level field (field in the type `Query`):  `bookById` which returns the details of a specific book.
+This schema defines one top level field (in the type `Query`):  `bookById` which returns the details of a specific book.
 
 It also defines the type `Book` which has the fields: `id`, `name`, `pageCount` and `author`.
 `author` is of type `Author`, which is defined after `Book`.
 
-> The Domain Specific Language shown above which is used to describe a schema is called Schema Definition Language or SDL.
+> The Domain Specific Language shown above which is used to describe a schema is called Schema Definition Language or SDL. More details about it can be found [here](https://graphql.org/learn/schema/).
 
 But so far it is just a normal text. We need to "bring it to live" by reading the file and parsing it.
 
-We are creating a new `GraphQLProvider` class in the package `com.graphqljava.tutorial.bookdetails` with an `init` method which will create a `GraphQL` instance:
+We create a new `GraphQLProvider` class in the package `com.graphqljava.tutorial.bookdetails` with an `init` method which will create a `GraphQL` instance:
 
 {{< highlight java "linenos=table" >}}
 
@@ -192,9 +196,7 @@ public class GraphQLProvider {
 {{< / highlight >}}
 <p/>
 
-
-We are using Guava to read the file at runtime from our classpath, then create a `GraphQLSchema` and `GraphQL` instance. This `GraphQL` instance is exposed as Spring Bean. The GraphQL Java Spring adapter will use that `GraphQL` instance to expose it the schema over HTTP on the default url `/graphql`. 
-
+We use Guava to read the file at runtime from our classpath, then create a `GraphQLSchema` and `GraphQL` instance. This `GraphQL` instance is exposed as Spring Bean. The GraphQL Java Spring adapter will use that `GraphQL` instance to make our schema available via HTTP on the default url `/graphql`. 
 
 What we still need to do is to implement the `buildSchema` method which creates the `GraphQLSchema` instance:
 
@@ -214,8 +216,7 @@ What we still need to do is to implement the `buildSchema` method which creates
                 .type(newTypeWiring("Query")
                         .dataFetcher("bookById", graphQLDataFetchers.getBookByIdDataFetcher()))
                 .type(newTypeWiring("Book")
-                        .dataFetcher("author", graphQLDataFetchers.getAuthorDataFetcher())
-                        .build())
+                        .dataFetcher("author", graphQLDataFetchers.getAuthorDataFetcher()))
                 .build();
     }
 {{< / highlight >}}
@@ -235,7 +236,7 @@ What we still need to do is to implement the `buildSchema` method which creates
 Probably the most important concept for a GraphQL Java server is a `DataFetcher`: 
 A `DataFetcher` fetches the Data for one field while the query is executed. 
 
-While GraphQL Java is executing a query it calls the appropriate `DataFetcher` for each field it encounters in query.
+While GraphQL Java is executing a query, it calls the appropriate `DataFetcher` for each field it encounters in query.
 A `DataFetcher` is an Interface with a single method, taking a single argument of type `DataFetcherEnvironment`:
 
 
@@ -246,7 +247,7 @@ public interface DataFetcher<T> {
 {{< / highlight >}}
 <p/>
 
-Important: **Every** field from the schema has a `DataFetcher` associated with. If you don't specify any `DataFetcher` for a specific field the default `PropertyDataFetcher` is used.
+Important: **Every** field from the schema has a `DataFetcher` associated with. If you don't specify any `DataFetcher` for a specific field, then the default `PropertyDataFetcher` is used.
 
 We are creating a new class `GraphQLDataFetchers` which contains a sample list of books and authors.
 
@@ -314,10 +315,9 @@ public class GraphQLDataFetchers {
 ## Source of the data
 We are getting our books and authors from a static list inside the class. This is made just for this tutorial. It is very important to understand that GraphQL doesn't dictate in anyway where the data comes from. This is the power of GraphQL: it can come from a static in memory list, from a database or an external service  
 
-
 ## Book DataFetcher
 Our first method `getBookByIdDataFetcher` returns a `DataFetcher` implementation which takes a `DataFetcherEnvironment` and returns a book.
-In our case this means we need to get the `id` argument from the `bookById` field and find the book with this specific id. If we can't find it we just return null. 
+In our case this means we need to get the `id` argument from the `bookById` field and find the book with this specific id. If we can't find it, we just return null. 
 
 The "id" in `String bookId = dataFetchingEnvironment.getArgument("id");` is the "id" from the `bookById` query field in the schema: 
 
@@ -328,27 +328,25 @@ type Query {
 ...
 {{< / highlight >}}
 
-
 ## Author DataFetcher
-Our second method `getAuthorDataFetcher` returns a `DataFetcher` for getting the author for a specific book.
-The difference to the book `DataFetcher` is that we don't have an argument, but we have a book instance.
-The result of the `DataFetcher` from the parent field is made available via `getSource`. This is an important concept to understand: the `DataFetcher` for each field in GraphQL are called from top to down and the previous result is the `source` property of the `DataFetcherEnvironment`. 
-
-We then use the previously fetched book to get the `authorId` and then look for that specific author in the same way we look for a specific book.
+Our second method `getAuthorDataFetcher`, returns a `DataFetcher` for getting the author for a specific book.
+Compared to the previously described book `DataFetcher`, we don't have an argument, but we have a book instance.
+The result of the `DataFetcher` from the parent field is made available via `getSource`. 
+This is an important concept to understand: the `DataFetcher` for each field in GraphQL are called in a top-down fashion and the parent's result is the `source` property of the child `DataFetcherEnvironment`.
 
+We then use the previously fetched book to get the `authorId` and look for that specific author in the same way we look for a specific book.
 
 # Try out the API
-This is all needed to actually build a working GraphQL API. After the starting the Spring Boot application the API is available on `http://localhost:8080/graphql`. 
+This is all that is needed to actually build a working GraphQL API. After the starting the Spring Boot application the API is available on `http://localhost:8080/graphql`. 
 
 The easiest way to try out and explore a GraphQL API is to use a tool like [GraphQL Playground](https://github.com/prisma/graphql-playground). Download it and run it.
 
 After starting it you will be asked for a URL, enter "http://localhost:8080/graphql". 
 
-After that you can query our example API and you should get back the result we mentioned in the beginning. It should look like this:
+After that, you can query our example API and you should get back the result we mentioned above in the beginning. It should look something like this:
 
 ![GraphQL Playground](/images/playground.png)
 
-
 # Complete example source code 
 
 The complete project with the full source code can be found here: https://github.com/graphql-java/tutorials/tree/master/book-details