Merge pull request #142 from apollostack/new-server

Docs for new apollo server

docs/_config.yml

@@ -29,14 +29,20 @@ sidebar_categories:
     - apollo-client/redux
   Apollo Server:
     - apollo-server/index
-    - apollo-server/guide
-    - apollo-server/tools
-    - apollo-server/generate-schema
-    - apollo-server/resolvers
-    - apollo-server/scalars
-    - apollo-server/mocking
-    - apollo-server/connectors
-    - apollo-server/errors
+    - apollo-server/setup
+    - apollo-server/requests
+    - apollo-server/graphiql
+    - apollo-server/migration
+  GraphQL Tools:
+    - graphql-tools/index
+#    - graphql-tools/guide
+#    - graphql-tools/tools
+    - graphql-tools/generate-schema
+    - graphql-tools/resolvers
+    - graphql-tools/scalars
+    - graphql-tools/mocking
+    - graphql-tools/connectors
+    - graphql-tools/errors
 github_repo: apollostack/docs
 content_root: source
 logo:

docs/package.json

@@ -3,7 +3,7 @@
   "version": "0.0.0",
   "private": true,
   "hexo": {
-    "version": "3.2.2"
+    "version": "3.2.0"
   },
   "dependencies": {
     "hexo": "^3.1.0",

docs/source/apollo-server/graphiql.md

@@ -0,0 +1,76 @@
+---
+title: GraphiQL
+order: 304
+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 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
+}
+```
+
+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';
+
+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';
+
+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 { graphqlHAPI } from 'apollo-server';
+
+server.register({
+    register: new GraphiQLHAPI(),
+    options: { endpointURL: '/graphql' },
+    routes: { prefix: '/graphiql' },
+});
+```
+
+
+<h2 id="graphiqlKoa">Using with Koa</h2>
+
+If you are using Koa, GraphiQL can be configured as follows:
+
+```js
+import { graphiqlKoa } from 'apollo-server';
+
+router.get('/graphiql', graphiqlKoa({ endpointURL: '/graphql' }));
+```

docs/source/apollo-server/index.md

@@ -1,14 +1,18 @@
 ---
-title: Overview
-order: 201
-description: How to install the Apollo GraphQL server tools.
+title: Installing
+order: 301
+description: How to install Apollo Server
 ---
 
-Apollo Server is an npm package and an opinionated guide for how to build a GraphQL server in JavaScript.
+Apollo Server is a community driven, flexible JavaScript GraphQL server for production use. You can use it with Express, Connect, HAPI and Koa.
 
 
 ```txt
 npm install apollo-server
 ```
 
-Apollo Server bundles a set of functions from the `graphql-tools` package, which are not just useful for building servers, but can also be used in the browser, for example to mock a backend during development or testing. Even though our guide recommends a specific way of building GraphQL servers, you can use these tools even if you don't follow our guide; they work with any GraphQL-JS schema, and each tool can be useful on its own.
+The following features distinguish Apollo Server from the reference implementation (express-graphql):
+- Apollo Server has a simpler interface and allows only POST requests, 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 expose 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 query whitelisting, which can make your app faster and your server more secure.

docs/source/apollo-server/migration.md

@@ -0,0 +1,99 @@
+---
+title: Migrating from v0.1
+order: 305
+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
+- 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 `apolloServer`.
+
+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(
+  `GraphQL 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,
+});
+
+graphQLServer.use('/graphql', bodyParser.json(), apolloExpress({
+  schema: executableSchema,
+}));
+
+graphqlServer.use('/graphiql', graphiqlExpress({
+  endpointURL: '/graphql',
+}));
+
+graphQLServer.listen(GRAPHQL_PORT, () => console.log(
+  `GraphQL Server is now running on http://localhost:${GRAPHQL_PORT}/graphql`
+));
+```

docs/source/apollo-server/requests.md

@@ -0,0 +1,38 @@
+---
+title: Sending requests
+order: 303
+description: How to send requests to Apollo Server
+---
+
+Apollo Server accepts only JSON-encoded POST requests. A valid request must contain eiter a `query` or an `operationName` (or both, in case of a named query), and may include `variables.` For example:
+
+```js
+{
+  "query": "query aTest{ 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{ test(who: $arg1) }",
+  "operationName": "aTest",
+  "variables": "{ \"arg1\": \"me\" }"
+}
+```
+
+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.