Merge pull request graphql#66 from lacker/graphqljs

Misc small docs fixes

Author: Kevin Lacker

site/code/index.html.js

@@ -30,7 +30,7 @@ Many different programming languages support GraphQL. This list contains some of
 ## GraphQL Server Libraries
 
   - [GraphQL.js](/graphql-js/getting-started/) ([github](https://github.com/graphql/graphql-js/)) ([npm](https://www.npmjs.com/package/graphql)): The reference implementation of the GraphQL specification, designed for running a GraphQL server in a Node.js environment.
-  - [express-graphql](/graphql-js/getting-started/) ([github](https://github.com/graphql/express-graphql)) ([npm](https://www.npmjs.com/package/express-graphql)): The reference implementation of a GraphQL API server over an Express webserver. You can use this to run GraphQL in conjunction with a regular Express webserver, or as a standalone GraphQL server.
+  - [express-graphql](/graphql-js/running-an-express-graphql-server/) ([github](https://github.com/graphql/express-graphql)) ([npm](https://www.npmjs.com/package/express-graphql)): The reference implementation of a GraphQL API server over an Express webserver. You can use this to run GraphQL in conjunction with a regular Express webserver, or as a standalone GraphQL server.
   - [Graphene](http://graphene-python.org/) ([github](https://github.com/graphql-python/graphene)): A Python library for building GraphQL APIs. Built-in support for [Relay](https://facebook.github.io/relay/), Django, SQLAlchemy, and Google App Engine.
   - [graphql-ruby](https://github.com/rmosolgo/graphql-ruby): A Ruby library for building GraphQL APIs. Built-in support for Relay and Rails.
   - [graphql-java](https://github.com/graphql-java/graphql-java): A Java library for building GraphQL APIs.

site/docs/APIReference-ExpressGraphQL.md

@@ -0,0 +1,35 @@
+---
+title: express-graphql
+layout: ../_core/CodeLayout
+category: API Reference
+permalink: /docs/api-reference-express-graphql/
+sublinks: graphqlHTTP
+next: /docs/api-reference-graphql/
+---
+
+The `express-graphql` module provides a simple way to create an [Express](https://expressjs.com/) server that runs a GraphQL API.
+
+```js
+import graphqlHTTP from 'express-graphql'; // ES6
+var graphqlHTTP = require('graphql'); // CommonJS
+```
+
+### graphqlHTTP
+
+```js
+graphqlHTTP({
+  schema: GraphQLSchema,
+  graphiql?: ?boolean,
+  rootValue?: ?any,
+  context?: ?any,
+  pretty?: ?boolean,
+  formatError?: ?Function,
+  validationRules?: ?Array<any>,
+}): Middleware
+```
+
+Constructs an Express application based on a GraphQL schema.
+
+See the [express-graphql tutorial](/graphql-js/running-an-express-graphql-server/) for sample usage.
+
+See the [GitHub README](https://github.com/graphql/express-graphql) for more extensive documentation of the details of this method.

site/docs/APIReference-Utilities.md

@@ -3,7 +3,7 @@ title: graphql/utilities
 layout: ../_core/CodeLayout
 category: API Reference
 permalink: /docs/api-reference-utilities/
-sublinks: introspectionQuery,buildClientSchema,printSchema,printIntrospectionSchema,buildASTSchema,typeFromAST,astFromValue,TypeInfo,isValidJSValue,isValidLiteralValue
+sublinks: introspectionQuery,buildClientSchema,printSchema,printIntrospectionSchema,buildASTSchema,typeFromAST,astFromValue,TypeInfo,isValidJSValue,isValidLiteralValue,buildSchema
 next: /docs/api-reference-validation/
 ---
 
@@ -37,6 +37,12 @@ var GraphQLUtilities = require('graphql/utilities'); // CommonJS
 *Schema Language*
 
 <ul class="apiIndex">
+  <li>
+    <a href="#buildschema">
+      <pre>function buildSchema</pre>
+      Builds a Schema object from GraphQL schema language.
+    </a>
+  </li>
   <li>
     <a href="#printschema">
       <pre>function printSchema</pre>
@@ -126,6 +132,14 @@ server-internal mechanisms.
 
 ## Schema Representation
 
+### buildSchema
+
+```js
+function buildSchema(source: string | Source): GraphQLSchema {
+```
+
+Creates a GraphQLSchema object from GraphQL schema language. The schema will use default resolvers. For more detail on the GraphQL schema language, see the [schema language docs](/learn/schema/) or this [schema language cheat sheet](https://wehavefaces.net/graphql-shorthand-notation-cheatsheet-17cd715861b6#.9oztv0a7n).
+
 ### printSchema
 
 ```js

site/docs/Guides-ConstructingTypes.md

@@ -3,7 +3,7 @@ title: Constructing Types
 layout: ../_core/CodeLayout
 category: Advanced Guides
 permalink: /graphql-js/constructing-types/
-next: /docs/api-reference-graphql/
+next: /docs/api-reference-express-graphql/
 ---
 
 For many apps, you can define a fixed schema when the application starts, and define it using GraphQL schema language. In some cases, it's useful to construct a schema programmatically. You can do this using the `GraphQLSchema` constructor.
@@ -41,7 +41,7 @@ var fakeDatabase = {
 };
 
 var root = {
-  user: function({id}) {
+  user: function ({id}) {
     return fakeDatabase[id];
   }
 };

site/docs/Tutorial-Authentication.md

@@ -30,7 +30,7 @@ function loggingMiddleware(req, res, next) {
 }
 
 var root = {
-  ip: function(args, request) {
+  ip: function (args, request) {
     return request.ip;
   }
 };

site/docs/Tutorial-GraphQLClients.md

@@ -31,10 +31,10 @@ xhr.responseType = 'json';
 xhr.open("POST", "/graphql");
 xhr.setRequestHeader("Content-Type", "application/json");
 xhr.setRequestHeader("Accept", "application/json");
-xhr.onload = function() {
+xhr.onload = function () {
   console.log('data returned:', xhr.response);
 }
-xhr.send(JSON.stringify({query:"{ hello }"}));
+xhr.send(JSON.stringify({query: "{ hello }"}));
 ```
 
 You should see the data returned, logged in the console:
@@ -43,6 +43,37 @@ You should see the data returned, logged in the console:
 data returned: Object { hello: "Hello world!" }
 ```
 
+In this example, the query was just a hardcoded string. As your application becomes more complex, and you add GraphQL endpoints that take arguments as described in [Passing Arguments](/graphql-js/passing-arguments/), you will want to construct GraphQL queries using variables in client code. You can do this by including a keyword prefixed with a dollar sign in the query, and passing an extra `variables` field on the payload.
+
+For example, let's say you're running the example server from [Passing Arguments](/graphql-js/passing-arguments/) that has a schema of
+
+```javascript
+type Query {
+  rollDice(numDice: Int!, numSides: Int): [Int]
+}
+```
+
+You could access this from JavaScript with the code:
+
+```javascript
+var dice = 3;
+var sides = 6;
+var xhr = new XMLHttpRequest();
+xhr.responseType = 'json';
+xhr.open("POST", "/graphql");
+xhr.setRequestHeader("Content-Type", "application/json");
+xhr.setRequestHeader("Accept", "application/json");
+xhr.onload = function () {
+  console.log('data returned:', xhr.response);
+}
+xhr.send(JSON.stringify({
+  query: "{ rollDice(numDice: $dice, numSides: $sides) }",
+  variables: { dice: dice, sides: sides },
+}));
+```
+
+Using this syntax for variables is a good idea because it automatically prevents bugs due to escaping, and it makes it easier to monitor your server.
+
 In general, it will take a bit more time to set up a GraphQL client like Relay, but it's worth it to get more features as your application grows. You might want to start out just using HTTP requests as the underlying transport layer, and switching to a more complex client as your application gets more complex.
 
 At this point you can write a client and server in GraphQL for an API that receives a single string. To do more, you will want to [learn how to use the other basic data types](/graphql-js/basic-types/).

site/docs/Tutorial-Mutations.md

@@ -25,10 +25,10 @@ Both mutations and queries can be handled by root resolvers, so the root that im
 ```javascript
 var fakeDatabase = {};
 var root = {
-  setMessage: function({message}) {
+  setMessage: function ({message}) {
     fakeDatabase.message = message;
   }
-  getMessage: function() {
+  getMessage: function () {
     return fakeDatabase.message;
   }
 };
@@ -87,16 +87,16 @@ var fakeDatabase = {};
 
 // The root provides the top-level API endpoints
 var root = {
-  getMessage: function({author}) {
+  getMessage: function ({author}) {
     return fakeDatabase[author];
   },
-  createMessage: function({message}) {
+  createMessage: function ({message}) {
     if (fakeDatabase[message.author]) {
       throw new Error('a message already exists with this author');
     }
     fakeDatabase[message.author] = message.content;
   },
-  updateMessage: function({message}) {
+  updateMessage: function ({message}) {
     if (!fakeDatabase[message.author]) {
       throw new Error('no message exists with this author');
     }

site/docs/Tutorial-ObjectTypes.md

@@ -50,7 +50,7 @@ class RandomDie {
 }
 
 var root = {
-  getDie: function({numSides}) {
+  getDie: function ({numSides}) {
     return new RandomDie(numSides || 6);
   }
 }
@@ -111,7 +111,7 @@ class RandomDie {
 
 // The root provides the top-level API endpoints
 var root = {
-  getDie: function({numSides}) {
+  getDie: function ({numSides}) {
     return new RandomDie(numSides || 6);
   }
 }

site/docs/Tutorial-PassingArguments.md

@@ -28,7 +28,7 @@ So far, our resolver functions took no arguments. When a resolver takes argument
 
 ```javascript
 var root = {
-  rollDice: function(args) {
+  rollDice: function (args) {
     var output = [];
     for (var i = 0; i < args.numDice; i++) {
       output.push(1 + Math.floor(Math.random() * (args.numSides || 6)));
@@ -42,7 +42,7 @@ It's convenient to use [ES6 destructuring assignment](https://developer.mozilla.
 
 ```javascript
 var root = {
-  rollDice: function({numDice, numSides}) {
+  rollDice: function ({numDice, numSides}) {
     var output = [];
     for (var i = 0; i < numDice; i++) {
       output.push(1 + Math.floor(Math.random() * (numSides || 6)));
@@ -70,7 +70,7 @@ var schema = buildSchema(`
 
 // The root provides a resolver function for each API endpoint
 var root = {
-  rollDice: function({numDice, numSides}) {
+  rollDice: function ({numDice, numSides}) {
     var output = [];
     for (var i = 0; i < numDice; i++) {
       output.push(1 + Math.floor(Math.random() * (numSides || 6)));
@@ -99,4 +99,27 @@ When you call this API, you have to pass each argument by name. So for the serve
 
 If you run this code with `node server.js` and browse to [http://localhost:4000/graphql](http://localhost:4000/graphql) you can try out this API.
 
+When you're passing arguments in code, it's generally better to avoid constructing the whole query string yourself. Instead, you can use `$` syntax to define variables in your query, and pass the variables as a separate map.
+
+For example, some JavaScript code that calls our server above is:
+
+```javascript
+var dice = 3;
+var sides = 6;
+var xhr = new XMLHttpRequest();
+xhr.responseType = 'json';
+xhr.open("POST", "/graphql");
+xhr.setRequestHeader("Content-Type", "application/json");
+xhr.setRequestHeader("Accept", "application/json");
+xhr.onload = function () {
+  console.log('data returned:', xhr.response);
+}
+xhr.send(JSON.stringify({
+  query: "{ rollDice(numDice: $dice, numSides: $sides) }",
+  variables: { dice: dice, sides: sides },
+}));
+```
+
+Using `$dice` and `$sides` as variables in GraphQL means we don't have to worry about escaping on the client side.
+
 With basic types and argument passing, you can implement anything you can implement in a REST API. But GraphQL supports even more powerful queries. You can replace multiple API calls with a single API call if you learn how to [define your own object types](/graphql-js/object-types/).