Adding a GraphQL endpoint

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.

Apollo Server options

Apollo Server accepts a GraphQLOptions object as its single argument. The GraphQLOptions object has the following properties:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// options object
const GraphQLOptions = {
schema: GraphQLSchema,
// values to be used as context and rootValue in resolvers
context?: any,
rootValue?: any,
// function used to format errors before returning them to clients
formatError?: Function,
// additional validation rules to be applied to client-specified queries
validationRules?: Array<ValidationRule>,
// function applied for each query in a batch to format parameters before passing them to `runQuery`
formatParams?: Function,
// function applied to each response before returning data to clients
formatResponse?: Function,
// a boolean option that will trigger additional debug logging if execution errors occur
debug?: boolean
}

Passing options as a function

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:

1
2
3
4
5
// 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.

Importing ES6 Modules

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 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.

Using with Express

The following code snippet shows how to use Apollo Server with Express:

1
2
3
4
5
6
7
8
9
10
11
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);

Using with Connect

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
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.

Using with Hapi

The following code snippet shows how to use Apollo Server with Hapi:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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:

1
2
3
4
5
6
7
8
9
server.register({
register: graphqlHapi,
options: {
path: '/graphql',
graphqlOptions: (request) => {
return { schema: myGraphQLSchema };
},
},
});

Using with Koa 2

The following code snippet shows how to use Apollo Server with Koa:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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.

1
2
3
4
5
6
router.post('/graphql', graphqlKoa((ctx) => {
return {
schema: myGraphQLSchema,
context: { userId: ctx.cookies.get('userId') }
};
}));
Edit on GitHub