Merge apollo-server docs from tools-docs

docs/source/graphiql.md

@@ -0,0 +1,81 @@
+---
+title: GraphiQL
+description: How to set up GraphiQL with Apollo Server
+---
+
+Apollo Server allows you to easily use [GraphiQL](https://github.com/graphql/graphiql). Here's how:
+
+<h2 id="graphiqlOptions">Configuring GraphiQL</h2>
+
+`graphiql<Express/Connect/Hapi/Koa>` accepts the following options object:
+
+```js
+const options = {
+  endpointURL: String, // URL for the GraphQL POST endpoint this instance of GraphiQL serves
+  query?: String, // optional query to pre-populate the GraphiQL UI with
+  operationName?: String, // optional operationName to pre-populate the GraphiQL UI with
+  variables?: Object, // optional variables to pre-populate the GraphiQL UI with
+  result?: Object, // optional result to pre-populate the GraphiQL UI with
+  passHeader?: String, // a string that will be added to the outgoing request header object (e.g "'Authorization': 'Bearer lorem ipsum'")
+  editorTheme?: String, // optional CodeMirror theme to be applied to the GraphiQL UI
+}
+```
+
+Apollo Server's `graphiql` middleware does not run any query passed to it, it simply renders it in the UI.
+To actually execute the query, the user must submit it via the GraphiQL UI, which will
+send the request to the GraphQL endpoint specified with `endpointURL`.
+
+<h2 id="graphiqlExpress">Using with Express</h2>
+
+If you are using Express, GraphiQL can be configured as follows:
+
+```js
+import { graphiqlExpress } from 'apollo-server-express';
+
+app.use('/graphiql', graphiqlExpress({
+  endpointURL: '/graphql',
+}));
+```
+
+
+<h2 id="graphiqlConnect">Using with Connect</h2>
+
+If you are using Connect, GraphiQL can be configured as follows:
+
+```js
+import { graphiqlConnect } from 'apollo-server-express';
+
+app.use('/graphiql', graphiqlConnect({
+  endpointURL: '/graphql',
+}));
+```
+
+
+<h2 id="graphiqlHapi">Using with Hapi</h2>
+
+If you are using Hapi, GraphiQL can be configured as follows:
+
+```js
+import { graphiqlHapi } from 'apollo-server-hapi';
+
+server.register({
+  register: graphiqlHapi,
+  options: {
+    path: '/graphiql',
+    graphiqlOptions: {
+      endpointURL: '/graphql',
+    },
+  },
+});
+```
+
+
+<h2 id="graphiqlKoa">Using with Koa 2</h2>
+
+If you are using Koa 2, GraphiQL can be configured as follows:
+
+```js
+import { graphiqlKoa } from 'apollo-server-koa';
+
+router.get('/graphiql', graphiqlKoa({ endpointURL: '/graphql' }));
+```

docs/source/index.md

@@ -0,0 +1,31 @@
+---
+title: Installing
+description: How to install Apollo Server
+---
+
+Apollo server is a flexible, community driven, production-ready HTTP Apollo Server plugin for Node.js.
+
+It works with any GraphQL schema built with [GraphQL.js](https://github.com/graphql/graphql-js), Facebook's reference JavaScript execution library, and you can use Apollo Server with all popular JavaScript HTTP servers, including Express, Connect, Hapi, Koa, Restify, and Lambda.
+
+This server can be queried from any popular GraphQL client, such as [Apollo](http://dev.apollodata.com) or [Relay](https://facebook.github.io/relay) because it supports all of the common semantics for sending GraphQL over HTTP, as [documented on graphql.org](http://graphql.org/learn/serving-over-http/). Apollo Server also supports some small extensions to the protocol, such as sending multiple GraphQL operations in one request. Read more on the [sending requests](/tools/apollo-server/requests.html) page.
+
+Install it with:
+
+```bash
+# Pick the one that matches your server framework
+npm install graphql apollo-server-express  # for Express or Connect
+npm install graphql apollo-server-hapi
+npm install graphql apollo-server-koa
+npm install graphql apollo-server-restify
+npm install graphql apollo-server-lambda
+npm install graphql apollo-server-micro
+```
+
+> A note for those who’ve used Apollo Server previously: You may notice we now import from `apollo-server-` rather than `graphql-server-` npm packages. We felt the rename better reflects that it’s part of the Apollo project and family of libraries.
+
+The following features distinguish Apollo Server from [express-graphql](https://github.com/graphql/express-graphql), Facebook's reference HTTP server implementation:
+
+- Apollo Server has a simpler interface and allows fewer ways of sending queries, which makes it a bit easier to reason about what's going on.
+- Apollo Server serves GraphiQL on a separate route, giving you more flexibility to decide when and how to serve it.
+- Apollo Server supports [query batching](https://medium.com/apollo-stack/query-batching-in-apollo-63acfd859862) which can help reduce load on your server.
+- Apollo Server has built-in support for persisted queries, which can make your app faster and your server more secure.

docs/source/migration-hapi.md

@@ -0,0 +1,46 @@
+---
+title: Migrating to v0.3
+description: How to migrate to Apollo Server 0.3 from 0.2.
+---
+
+> Note: This guide assumes you were previously up to date with `apollo-server` series `0.2.x`. If you are currently using `0.1`, consult the [previous migration guide](migration.md).
+
+Version 0.3.0 of Apollo Server contains a couple of breaking changes in the Hapi plugin API.
+The most notable changes are:
+
+- the plugin class has been replaced as a function to be more idiomatic
+- the plugin name has been renamed to use camelcase
+- the options object has been extended to support additional routing options
+
+The following code snippet for Hapi Apollo 0.2.x
+
+```js
+import { ApolloHAPI } from 'apollo-server';
+...
+server.register({
+    register: new ApolloHAPI(),
+    options: { schema: myGraphQLSchema },
+    routes: { prefix: '/graphql' },
+});
+```
+
+... should be written as follows for Hapi Apollo 0.3.x
+
+```js
+import { apolloHapi } from 'apollo-server';
+...
+server.register({
+    register: apolloHapi,
+    options: {
+      path: '/graphql',
+      apolloOptions: {
+        schema: myGraphQLSchema,
+      },
+      route: {
+        cors: true
+      }
+    },
+});
+```
+
+*NOTE:* That you can now pass additional routing configuration via the route options

docs/source/migration.md

@@ -0,0 +1,101 @@
+---
+title: Migrating to v0.2
+description: How to migrate from an older version of Apollo Server
+---
+
+Version 0.2.0 of Apollo Server contains several breaking changes in the API.
+The most notable changes are:
+
+- the `apolloServer` function no longer exists and was replaced with `apolloExpress`.
+- `apolloExpress` no longer accepts shorthand type definitions
+- `apolloExpress` doesn't have the `resolvers`, `mocks` and `connectors` options.
+- `apolloExpress` doesn't include GraphiQL any more
+- `context`: if you use connectors in your schema, don't forget to setup default `context` to at least an empty object, it can't be `undefined` in this case
+- Apollo Server no longer accepts GET requests or parameters in the URL
+- `apolloExpress` no longer parses the HTTP body automatically
+
+
+In order to make updating from an older version of Apollo Server easier, this guide
+shows how to use `graphql-tools` together with `apolloExpress` and `graphiqlExpress` to
+replace the old `apolloServer` function.
+
+The three main differences between the old and the new approach are:
+1. generating the schema is now done with `graphql-tools`, Apollo Server only uses the finished schema.
+2. `bodyParser` has to be used to parse requests before passing them to `expressApollo`
+3. GraphiQL now has to be served on a separate path
+
+The following code snippet in Apollo Server 0.1.x
+
+```js
+import express from 'express';
+import { apolloServer } from 'apollo-server';
+import Schema from './data/schema';
+import Mocks from './data/mocks';
+import Resolvers from './data/resolvers';
+import Connectors from './data/connectors';
+
+const GRAPHQL_PORT = 8080;
+
+const graphQLServer = express();
+
+graphQLServer.use('/graphql', apolloServer({
+  graphiql: true,
+  schema: Schema,
+  resolvers: Resolvers,
+  connectors: Connectors,
+  mocks: Mocks,
+}));
+
+graphQLServer.listen(GRAPHQL_PORT, () => console.log(
+  `Apollo Server is now running on http://localhost:${GRAPHQL_PORT}/graphql`
+));
+```
+
+... should be written as follows in Apollo Server 0.2.x and above:
+
+
+```js
+import express from 'express';
+
+import Schema from './data/schema';
+import Mocks from './data/mocks';
+import Resolvers from './data/resolvers';
+import Connectors from './data/connectors';
+
+// NEW or changed imports:
+import { apolloExpress, graphiqlExpress } from 'apollo-server';
+import { makeExecutableSchema, addMockFunctionsToSchema } from 'graphql-tools';
+import bodyParser from 'body-parser';
+
+
+
+const GRAPHQL_PORT = 8080;
+
+const graphQLServer = express();
+
+const executableSchema = makeExecutableSchema({
+  typeDefs: Schema,
+  resolvers: Resolvers,
+  connectors: Connectors,
+});
+
+addMockFunctionsToSchema({
+  schema: executableSchema,
+  mocks: Mocks,
+  preserveResolvers: true,
+});
+
+// `context` must be an object and can't be undefined when using connectors
+graphQLServer.use('/graphql', bodyParser.json(), apolloExpress({
+  schema: executableSchema,
+  context: {}, //at least(!) an empty object
+}));
+
+graphQLServer.use('/graphiql', graphiqlExpress({
+  endpointURL: '/graphql',
+}));
+
+graphQLServer.listen(GRAPHQL_PORT, () => console.log(
+  `Apollo Server is now running on http://localhost:${GRAPHQL_PORT}/graphql`
+));
+```

docs/source/requests.md

@@ -0,0 +1,58 @@
+---
+title: Sending requests
+description: How to send requests to Apollo Server
+---
+
+Apollo Server accepts both GET and POST requests.
+
+<h2 id="postRequests">POST requests</h2>
+
+Apollo Server accepts POST requests with a JSON body. A valid request must contain either a `query` or an `operationName` (or both, in case of a named query), and may include `variables.` Here's an example for a valid body of a post request:
+
+```js
+{
+  "query": "query aTest($arg1: String!) { test(who: $arg1) }",
+  "operationName": "aTest",
+  "variables": { "arg1": "me" }
+}
+```
+
+Variables can be an object or a JSON-encoded string. I.e. the following is equivalent to the previous query:
+
+```js
+{
+  "query": "query aTest($arg1: String!) { test(who: $arg1) }",
+  "operationName": "aTest",
+  "variables": "{ \"arg1\": \"me\" }"
+}
+```
+
+<h3 id="batching">Batching</h3>
+
+A batch of queries can be sent by simply sending a JSON-encoded array of queries, e.g.
+
+```js
+[
+  { "query": "{ testString }" },
+  { "query": "query q2{ test(who: \"you\" ) }" }
+]
+```
+
+If a batch of queries is sent, the response will be an array of GraphQL responses.
+
+If Apollo Server is running under a different origin than your client, you will need to enable CORS support on the server, or proxy the GraphQL requests through a web server under the main origin.
+
+
+<h2 id="getRequests">GET requests</h2>
+
+Apollo Server also accepts GET requests. A GET request must pass query and optionally variables and operationName in the URL.
+
+Here is the same query from above in a well-formatted GET request to Apollo Server:
+```
+GET /graphql?query=query%20aTest(%24arg1%3A%20String!)%20%7B%20test(who%3A%20%24arg1)%20%7D&operationName=aTest&variables=me
+```
+
+caveat: Mutations cannot be executed via GET requests.
+
+
+

docs/source/setup.md

@@ -0,0 +1,175 @@
+---
+title: Adding a GraphQL endpoint
+description: How to add a GraphQL endpoint to your server.
+---
+
+Apollo Server has a slightly different API depending on which server integration you are using, but all of the packages share the same core implementation and options format.
+
+<h2 id="graphqlOptions">Apollo Server options</h2>
+
+Apollo Server accepts a `GraphQLOptions` object as its single argument. The `GraphQLOptions` object has the following properties:
+
+```js
+// options object
+const GraphQLOptions = {
+  schema: GraphQLSchema,
+
+  // rootValue passed to GraphQL execution
+  rootValue?: any,
+
+  // the context passed to GraphQL execution
+  context?: any,
+
+  // Formatting function applied to all errors before response is sent
+  formatError?: Function,
+
+  // a function called for logging events such as execution times
+  logFunction?: Function,
+  // a function applied to the parameters of every invocation of runQuery
+  formatParams?: Function,
+
+  // * - (optional) validationRules: extra validation rules applied to requests
+  validationRules?: Array<ValidationRule>,
+
+  // a function applied to each graphQL execution result
+  formatResponse?: Function
+
+  // a custom default field resolver
+  fieldResolver?: Function
+
+  // a boolean that will print additional debug logging if execution errors occur
+  debug?: boolean
+}
+```
+
+<h3 id="options-function">Passing options as a function</h3>
+
+Alternatively, Apollo Server can accept a function which takes the request as input and returns a GraphQLOptions object or a promise that resolves to one:
+
+```js
+// example options function (for express)
+graphqlExpress(request => ({
+  schema: typeDefinitionArray,
+  context: { user: request.session.user }
+}))
+```
+
+This is useful if you need to attach objects to your context on a per-request basis, for example to initialize user data, caching tools like `dataloader`, or set up some API keys.
+
+<h2 id="importingESModules">Importing ES6 Modules</h2>
+
+Currently, the ES6 Module import syntax used in these examples is not implemented in Nodejs 6.x,7.x, and earlier versions.  To use these examples, you will need to configure an external tool like [Babel](https://babeljs.io/) that will transpile the import statements into standard require statements.  For example, `import express from 'express';` would become  `var express = require('express');`.  If you don't want to use an external transpiler, you can manually convert the imports to requires using the example format.
+
+<h2 id="graphqlExpress">Using with Express</h2>
+
+The following code snippet shows how to use Apollo Server with Express:
+
+```js
+import express from 'express';
+import bodyParser from 'body-parser';
+import { graphqlExpress } from 'apollo-server-express';
+
+const PORT = 3000;
+
+var app = express();
+
+app.use('/graphql', bodyParser.json(), graphqlExpress({ schema: myGraphQLSchema }));
+
+app.listen(PORT);
+```
+
+<h2 id="graphqlConnect">Using with Connect</h2>
+
+Connect is so similar to Express that the integration is in the same package. The following code snippet shows how to use Apollo Server with Connect:
+
+```js
+import connect from 'connect';
+import bodyParser from 'body-parser';
+import { graphqlConnect } from 'apollo-server-express';
+import http from 'http';
+
+const PORT = 3000;
+
+var app = connect();
+
+app.use('/graphql', bodyParser.json());
+app.use('/graphql', graphqlConnect({ schema: myGraphQLSchema }));
+
+http.createServer(app).listen(PORT);
+```
+
+The arguments passed to `graphqlConnect` are the same as those passed to `graphqlExpress`.
+
+<h2 id="graphqlHapi">Using with Hapi</h2>
+
+The following code snippet shows how to use Apollo Server with Hapi:
+
+```js
+import hapi from 'hapi';
+import { graphqlHapi } from 'apollo-server-hapi';
+
+const server = new hapi.Server();
+
+const HOST = 'localhost';
+const PORT = 3000;
+
+server.connection({
+    host: HOST,
+    port: PORT,
+});
+
+server.register({
+  register: graphqlHapi,
+  options: {
+    path: '/graphql',
+    graphqlOptions: { schema: myGraphQLSchema },
+  },
+});
+```
+
+`graphqlOptions` can also be a callback or a promise:
+
+```js
+server.register({
+  register: graphqlHapi,
+  options: {
+    path: '/graphql',
+    graphqlOptions: (request) => {
+      return { schema: myGraphQLSchema };
+    },
+  },
+});
+```
+
+<h2 id="graphqlKoa">Using with Koa 2</h2>
+
+The following code snippet shows how to use Apollo Server with Koa:
+
+```js
+import koa from 'koa';
+import koaRouter from 'koa-router';
+import koaBody from 'koa-bodyparser';
+import { graphqlKoa } from 'apollo-server-koa';
+
+const app = new koa();
+const router = new koaRouter();
+const PORT = 3000;
+
+app.use(koaBody());
+
+router.post('/graphql', graphqlKoa({ schema: myGraphQLSchema }));
+app.use(router.routes());
+app.use(router.allowedMethods());
+app.listen(PORT);
+```
+
+`graphqlOptions` can also be a callback that returns a GraphQLOptions or returns a promise that resolves to GraphQLOptions. This function takes a koa 2 `ctx` as its input.
+
+```js
+router.post('/graphql', graphqlKoa((ctx) => {
+  return {
+    schema: myGraphQLSchema,
+    context: { userId: ctx.cookies.get('userId') }
+  };
+}));
+```