add learn introduction page

Author: leebyron

site/learn/BestPractice-Authorization.md

@@ -3,7 +3,6 @@ title: Authorization
 layout: ../_core/DocsLayout
 category: Best Practices
 permalink: /learn/authorization/
-next: /learn/serving-over-http/
 ---
 
 > Delegate authorization logic to the business logic layer

site/learn/BestPractice-ServingOverHTTP.md

@@ -3,20 +3,21 @@ title: Serving over HTTP
 layout: ../_core/DocsLayout
 category: Best Practices
 permalink: /learn/serving-over-http/
+next: /learn/authorization/
 ---
 
 HTTP is the most common choice for client-server protocol when using GraphQL because of its ubiquity. Here are some guidelines for setting up a GraphQL server to operate over HTTP.
 
-### Web Request Pipeline
+## Web Request Pipeline
 Most modern web frameworks use a pipeline model where requests are passed through a stack of middleware (AKA filters/plugins). As the request flows through the pipeline, it can be inspected, transformed, modified, or terminated with a response. GraphQL should be placed after all authentication middleware, so that you have access to the same session and user information you would in your HTTP endpoint handlers.
 
-### URIs, Routes
+## URIs, Routes
 HTTP is commonly associated with REST, which uses "resources" as its core concept. In contrast, GraphQL's conceptual model is an entity graph. As a result, entities in GraphQL are not identified by URLs. Instead, a GraphQL server operates on a single URL/endpoint, usually `/graphql`, and all GraphQL requests for a given service should be directed at this endpoint.
 
-### HTTP Methods, Headers, and Body
+## HTTP Methods, Headers, and Body
 Your GraphQL HTTP server should handle the HTTP GET and POST methods.
 
-#### GET request
+### GET request
 
 When receiving an HTTP GET request, the GraphQL query should be specified in the "query" query string. For example, if we wanted to execute the following GraphQL query:
 
@@ -36,15 +37,15 @@ http://myapi/graphql?query={me{name}}
 
 Query variables can be sent as a JSON-encoded string in an additional query parameter called `variables`.  If the query contains several named operations, an `operationName` query parameter can be used to control which one should be executed.
 
-#### POST request
+### POST request
 
 A standard GraphQL POST request should use the `application/json` content type, and include a JSON-encoded body of the following form:
 
 ```js
 {
   "query": "...",
   "operationName": "...",
-  "variables": { variable1: value, ... }  
+  "variables": { variable1: value, ... }
 }
 ```
 
@@ -57,7 +58,7 @@ In addition to the above, we recommend supporting two additional cases:
 
 If you're using express-graphql, you already get these behaviors for free.
 
-### Response
+## Response
 
 Regardless of the method by which the query and variables were sent, the response should be returned in the body of the request in JSON format. As mentioned in the spec, a query might result in some data and some errors, and those should be returned in a JSON object of the form:
 
@@ -70,7 +71,7 @@ Regardless of the method by which the query and variables were sent, the respons
 
 If there were no errors returned, the `"errors"` field should not be present on the response. If no data is returned, [according to the GraphQL spec](http://facebook.github.io/graphql/#sec-Data), the `"data"` field should only be included if the error occurred during execution.
 
-### GraphiQL
+## GraphiQL
 GraphiQL is useful during testing and development but should be disabled in production by default. If you are using express-graphql, you can toggle it based on the NODE_ENV environment variable:
 
 ```
@@ -80,5 +81,5 @@ app.use('/graphql', graphqlHTTP({
 }));
 ```
 
-### Node
+## Node
 If you are using NodeJS, we recommend using either [express-graphql](https://github.com/graphql/express-graphql) or [apollo-server](https://github.com/apollostack/apollo-server).

site/learn/BestPractice-ThinkingInGraphs.md

@@ -3,15 +3,15 @@ title: Thinking in Graphs
 layout: ../_core/DocsLayout
 category: Best Practices
 permalink: /learn/thinking-in-graphs/
-next: /learn/authorization/
+next: /learn/serving-over-http/
 ---
 
-### It's Graphs All the Way Down [\*](https://en.wikipedia.org/wiki/Turtles_all_the_way_down)
+## It's Graphs All the Way Down [\*](https://en.wikipedia.org/wiki/Turtles_all_the_way_down)
 > With GraphQL, you model your business domain as a graph
 
 Graphs are powerful tools for modeling many real-world phenomena because they resemble our natural mental models and verbal descriptions of the underlying process. With GraphQL, you model your business domain as a graph by defining a schema; within your schema, you define different types of nodes and how they connect/relate to one another. On the client, this creates a pattern similar to Object-Oriented Programming: types that reference other types. On the server, since GraphQL only defines the interface, you have the freedom to use it with any backend (new or legacy!).
 
-### Shared Language
+## Shared Language
 > Naming things is a hard but important part of building intuitive APIs
 
 Think of your GraphQL schema as an expressive shared language for your team and your users. To build a good schema, examine the everyday language you use to describe your business. For example, let's try to describe an email app in plain english:
@@ -50,7 +50,7 @@ fragment previewInfo on Email {
 }
 ```
 
-### Business Logic Layer
+## Business Logic Layer
 > Your business logic layer should act as the single source of truth for enforcing business domain rules
 
 Where should you define the actual business logic? Where should you perform validation and authorization checks? The answer: inside a dedicated business logic layer. Your business logic layer should act as the single source of truth for enforcing business domain rules.
@@ -66,7 +66,7 @@ Sometimes, you will find yourself working with legacy data sources that do not p
 
 Build your GraphQL schema to express "what" rather than "how". Then you can improve your implementation details without breaking the interface with older clients.
 
-### One Step at a time
+## One Step at a time
 > Get validation and feedback more frequently
 
 Don't try to model your entire business domain in one sitting. Rather, build only the part of the schema that you need for one scenario at a time. By gradually expanding the schema, you will get validation and feedback more frequently to steer you toward building the right solution.

site/learn/Introduction.md

@@ -0,0 +1,81 @@
+---
+title: Introduction
+layout: ../_core/DocsLayout
+category: Learn
+permalink: /learn/
+next: /learn/queries/
+---
+
+GraphQL is a query language for your API, and a server-side runtime for executing queries by using a type system you define for your data. GraphQL isn't tied to any specific database or storage engine and is instead backed by your existing code and data.
+
+A GraphQL service is created by defining types and fields on those types, then providing functions for each field on each type. For example, a GraphQL service that tells us who the logged in user is (`me`) as well as that User's name might look something like this:
+
+```graphql
+type Query {
+  me: User
+}
+
+type User {
+  id: ID
+  name: String
+}
+```
+
+Along with functions for each field on each type:
+
+```js
+function Query_me(request) {
+  return request.auth.user;
+}
+
+function User_name(user) {
+  return user.getName();
+}
+```
+
+Once a GraphQL service is running (typically at a URL on a web service), it can be sent GraphQL queries to validate and execute. A received query is first checked to ensure it only refers to the types and fields defined, then runs the provided functions to produce a result.
+
+For example the query:
+
+```graphql
+{
+  me {
+    name
+  }
+}
+```
+
+Could produce the JSON result:
+
+```json
+{
+  "me": {
+    "name": "Luke Skywalker"
+  }
+}
+```
+
+Learn more about GraphQL: the query language, type system, how the GraphQL service works, and best practices for using GraphQL:
+
+## Core Concepts
+
+Start here to get a solid understanding of GraphQL and how it works.
+
+  - [Query Language](/learn/queries/)
+  - [Type System](/learn/schema/)
+  - Validation
+  - Execution
+  - Introspection
+
+## Best Practices
+
+Ready to start using GraphQL? Follow these guidelines to get a better understanding of how to approach common topics.
+
+  - [Thinking in Graphs](/learn/thinking-in-graphs/)
+  - [Serving Over HTTP](/learn/serving-over-http/)
+  - [Authorization](/learn/authorization/)
+  - Domain Modeling
+  - Pagination
+  - Versioning
+  - Performance
+  - Security