apollographql/apollo-server

Name: apollo-server

Owner: Apollo GraphQL

Description: :earth_africa: GraphQL server for Express, Connect, Hapi, Koa and more

Created: 2016-04-21 09:26:01.0

Updated: 2018-01-18 17:29:46.0

Pushed: 2018-01-18 16:26:57.0

Homepage: https://www.apollographql.com/docs/apollo-server/

Size: 1008

Language: TypeScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

GraphQL Server for Express, Connect, Hapi, Koa, and more

Also supports: Restify, Micro, Azure Functions, AWS Lambda and Adonis Framework

Apollo Server is a community-maintained open-source GraphQL server. It works with pretty much all Node.js HTTP server frameworks, and we're happy to take PRs for more! Apollo Server works with any GraphQL schema built with GraphQL.js, so you can build your schema with that directly or with a convenience library such as graphql-tools.

Documentation

Read the docs!

Principles

Apollo Server is built with the following principles in mind:

• By the community, for the community: Apollo Server's development is driven by the needs of developers
• Simplicity: by keeping things simple, Apollo Server is easier to use, easier to contribute to, and more secure
• Performance: Apollo Server is well-tested and production-ready - no modifications needed

Anyone is welcome to contribute to Apollo Server, just read CONTRIBUTING.md, take a look at the roadmap and make your first PR!

Getting started

Apollo Server is super easy to set up. Just npm install apollo-server-<variant>, write a GraphQL schema, and then use one of the following snippets to get started. For more info, read the Apollo Server docs. To experiment a live example of Apollo Server, create an Apollo Launchpad. Downloading the pad will provide you a local Apollo Server project.

Installation

Just run npm install --save apollo-server-<variant> and you're good to go!

where <variant> is one of the following:

• express
• koa
• hapi
• restify
• lambda
• micro
• azure-functions
• adonis

Express

rt express from 'express';
rt bodyParser from 'body-parser';
rt { graphqlExpress, graphiqlExpress } from 'apollo-server-express';

t myGraphQLSchema = // ... define or import your schema here!
t PORT = 3000;

t app = express();

odyParser is needed just for POST.
use('/graphql', bodyParser.json(), graphqlExpress({ schema: myGraphQLSchema }));
get('/graphiql', graphiqlExpress({ endpointURL: '/graphql' })); // if you want GraphiQL enabled

listen(PORT);

Connect

rt connect from 'connect';
rt bodyParser from 'body-parser';
rt query from 'connect-query';
rt { graphqlConnect } from 'apollo-server-express';
rt http from 'http';

t PORT = 3000;

t app = connect();

odyParser is only needed for POST.
use('/graphql', bodyParser.json());
uery is only needed for GET.
use('/graphql', query());
use('/graphql', graphqlConnect({ schema: myGraphQLSchema }));

.createServer(app).listen(PORT);

Hapi

Now with the Hapi plugins graphqlHapi and graphiqlHapi you can pass a route object that includes options to be applied to the route. The example below enables CORS on the /graphql route.

The code below requires Hapi 17 or higher.

rt Hapi from 'hapi';
rt { graphqlHapi } from 'apollo-server-hapi';

t HOST = 'localhost';
t PORT = 3000;

c function StartServer() {
nst server = new Hapi.server({
host: HOST,
port: PORT,
;

ait server.register({
plugin: graphqlHapi,
options: {
  path: '/graphql',
  graphqlOptions: {
    schema: myGraphQLSchema,
  },
  route: {
    cors: true,
  },
},
;

y {
await server.start();
catch (err) {
console.log(`Error while starting server: ${err.message}`);


nsole.log(`Server running at: ${server.info.uri}`);


tServer();

Koa

rt koa from 'koa'; // koa@2
rt koaRouter from 'koa-router'; // koa-router@next
rt koaBody from 'koa-bodyparser'; // koa-bodyparser@next
rt { graphqlKoa, graphiqlKoa } from 'apollo-server-koa';

t app = new koa();
t router = new koaRouter();
t PORT = 3000;

oaBody is needed just for POST.
er.post('/graphql', koaBody(), graphqlKoa({ schema: myGraphQLSchema }));
er.get('/graphql', graphqlKoa({ schema: myGraphQLSchema }));

er.get('/graphiql', graphiqlKoa({ endpointURL: '/graphql' }));

use(router.routes());
use(router.allowedMethods());
listen(PORT);

Restify

rt restify from 'restify';
rt { graphqlRestify, graphiqlRestify } from 'apollo-server-restify';

t PORT = 3000;

t server = restify.createServer({
tle: 'Apollo Server',


t graphQLOptions = { schema: myGraphQLSchema };

er.use(restify.plugins.bodyParser());
er.use(restify.plugins.queryParser());

er.post('/graphql', graphqlRestify(graphQLOptions));
er.get('/graphql', graphqlRestify(graphQLOptions));

er.get('/graphiql', graphiqlRestify({ endpointURL: '/graphql' }));

er.listen(PORT, () => console.log(`Listening on ${PORT}`));

AWS Lambda

Lambda function should be run with Node.js 4.3 or v6.1. Requires an API Gateway with Lambda Proxy Integration.

server = require('apollo-server-lambda');

rts.handler = server.graphqlLambda({ schema: myGraphQLSchema });

ZEIT Micro

Requires the Micro module

t server = require('apollo-server-micro');

le.exports = server.microGraphql({ schema: myGraphQLSchema });

Adonis Framework

tart/routes.js
t { graphqlAdonis } = require('apollo-server-adonis');

t Route = use('Route');

e.post('/graphql', graphqlAdonis({ schema: myGraphQLSchema }));
e.get('/graphql', graphqlAdonis({ schema: myGraphQLSchema }));

Options

Apollo Server can be configured with an options object with the following fields:

• schema: the GraphQLSchema to be used
• context: the context value passed to resolvers during GraphQL execution
• rootValue: the value passed to the first resolve function
• formatError: a function to apply to every error before sending the response to clients
• validationRules: additional GraphQL validation rules to be applied to client-specified queries
• formatParams: a function applied for each query in a batch to format parameters before execution
• formatResponse: a function applied to each response after execution
• tracing: when set to true, collect and expose trace data in the Apollo Tracing format

All options except for schema are optional.

Whitelisting

The formatParams function can be used in combination with the OperationStore to enable whitelisting.

t store = new OperationStore(Schema);
e.put('query testquery{ testString }');
hqlOptions = {
hema: Schema,
rmatParams(params) {
params['query'] = store.get(params.operationName);
return params;

Comparison with express-graphql

Both Apollo Server and express-graphql are GraphQL servers for Node.js, built on top of the graphql-js reference implementation, but there are a few key differences:

• express-graphql works with Express and Connect, Apollo Server supports Express, Connect, Hapi, Koa and Restify.
• Compared to express-graphql, Apollo Server has a simpler interface and supports exactly one way of passing queries.
• Apollo Server separates serving GraphiQL (an in-browser IDE for exploring GraphQL) from responding to GraphQL requests.
• express-graphql contains code for parsing HTTP request bodies, Apollo Server leaves that to standard packages like body-parser.
• Apollo Server includes an OperationStore to easily manage whitelisting.
• Apollo Server is built with TypeScript.

application/graphql requests

express-graphql supports the application/graphql Content-Type for requests, which is an alternative to application/json request with only the query part sent as text. In the same way that we use bodyParser.json to parse application/json requests for apollo-server, we can use bodyParser.text plus one extra step in order to also parse application/graphql requests. Here's an example for Express:

rt express from 'express';
rt bodyParser from 'body-parser';
rt { graphqlExpress } from 'apollo-server-express';

t myGraphQLSchema = // ... define or import your schema here!

t helperMiddleware = [
bodyParser.json(),
bodyParser.text({ type: 'application/graphql' }),
(req, res, next) => {
    if (req.is('application/graphql')) {
        req.body = { query: req.body };
    }
    next();
}


ess()
.use('/graphql', ...helperMiddleware, graphqlExpress({ schema: myGraphQLSchema }))
.listen(3000);

Apollo Server Development

If you want to develop Apollo Server locally you must follow the following instructions:

• Fork this repository

• Install the Apollo Server project in your computer

clone https://github.com/[your-user]/apollo-server
pollo-server
install
ackages/apollo-server-<variant>/
link

• Install your local Apollo Server in other App

/myApp
link apollo-server-<variant>