hiro/apollo-server
1
0
Fork 0
mirror of https://github.com/vale981/apollo-server synced 2025-03-05 17:51:40 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

update README's and remove docs for registerServer (fixes #1216)

Browse source
This commit is contained in:
Evans Hauser 2018-06-22 17:51:56 -07:00
parent 049a61a368
commit 846579db33
No known key found for this signature in database
GPG key ID: 88AF586817F52EEC
7 changed files with 146 additions and 269 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

317
README.md
View file

@ -4,13 +4,11 @@
[![Build Status](https://circleci.com/gh/apollographql/apollo-cache-control-js.svg?style=svg)](https://circleci.com/gh/apollographql/apollo-cache-control-js)
[![Get on Slack](https://img.shields.io/badge/slack-join-orange.svg)](https://www.apollographql.com/#slack)
FIXME update README for 2.x; refer to 1.x branch for currently unsupported web frameworks and encourage community to help port ApolloServer to other frameworks.
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](https://github.com/graphql/graphql-js), so you can build your schema with that directly or with a convenience library such as [graphql-tools](https://www.apollographql.com/docs/graphql-tools/).
## Documentation
[Read the docs!](https://www.apollographql.com/docs/apollo-server/)
[Read the docs!](https://www.apollographql.com/docs/apollo-server/v2)
## Principles
@ -24,259 +22,178 @@ Anyone is welcome to contribute to Apollo Server, just read [CONTRIBUTING.md](./
## 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](https://www.apollographql.com/docs/apollo-server/). To experiment a live example of Apollo Server, create an [Apollo Launchpad](https://launchpad.graphql.com). Downloading the pad will provide you a local Apollo Server project.
Apollo Server is super easy to set up. Just `npm install apollo-server-<integration>`, write a GraphQL schema, and then use one of the following snippets to get started. For more info, read the [Apollo Server docs](https://www.apollographql.com/docs/apollo-server/v2).
### Installation
Just run `npm install --save apollo-server-<variant>` and you're good to go!
Run `npm install --save apollo-server-<integration>` and you're good to go!
where `<variant>` is one of the following:
```js
const { ApolloServer, gql } = require('apollo-server');
// The GraphQL schema
const typeDefs = gql`
type Query {
"A simple type for getting started!"
hello: String
}
`;
// A map of functions which return data for the schema.
const resolvers = {
Query: {
hello: () => 'world'
}
};
const server = new ApolloServer({
typeDefs,
resolvers,
});
```
## Integrations
Often times, Apollo Server needs to be run with a particular integration. To start, run `npm install --save apollo-server-<integration>` where `<integration>` is one of the following:
- `express`
- `koa`
- `hapi`
- `restify`
- `lambda`
- `micro`
- `azure-functions`
- `adonis`
- `cloudflare`
If a framework is not on this list and it should be supported, please open a PR.
### Express
```js
import express from 'express';
import bodyParser from 'body-parser';
import { graphqlExpress, graphiqlExpress } from 'apollo-server-express';
const express = require('express');
const { ApolloServer, gql } = require('apollo-server-express');
const myGraphQLSchema = // ... define or import your schema here!
const PORT = 3000;
// Construct a schema, using GraphQL schema language
const typeDefs = gql`
type Query {
hello: String
}
`;
// Provide resolver functions for your schema fields
const resolvers = {
Query: {
hello: () => 'Hello world!',
},
};
const server = new ApolloServer({ typeDefs, resolvers });
const app = express();
server.applyMiddleware({ app });
// bodyParser is needed just for POST.
app.use('/graphql', bodyParser.json(), graphqlExpress({ schema: myGraphQLSchema }));
app.get('/graphiql', graphiqlExpress({ endpointURL: '/graphql' })); // if you want GraphiQL enabled
app.listen(PORT);
app.listen({ port: 4000 }, () =>
console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`)
)
```
### Connect
```js
import connect from 'connect';
import bodyParser from 'body-parser';
import query from 'connect-query';
import { graphqlConnect } from 'apollo-server-express';
import http from 'http';
const connect = require('connect');
const { ApolloServer, gql } = require('apollo-server-express');
const query = require('qs-middleware');
const PORT = 3000;
// Construct a schema, using GraphQL schema language
const typeDefs = gql`
type Query {
hello: String
}
`;
// Provide resolver functions for your schema fields
const resolvers = {
Query: {
hello: () => 'Hello world!',
},
};
const server = new ApolloServer({ typeDefs, resolvers });
const app = connect();
const path = '/graphql';
// bodyParser is only needed for POST.
app.use('/graphql', bodyParser.json());
// query is only needed for GET.
app.use('/graphql', query());
app.use('/graphql', graphqlConnect({ schema: myGraphQLSchema }));
server.use(query());
server.applyMiddleware({ app, path });
http.createServer(app).listen(PORT);
app.listen({ port: 4000 }, () =>
console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`)
)
```
### Hapi
> Note; `qs-middleware` is only required if running outside of Meteor
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.
### Hapi
The code below requires Hapi 17 or higher.
```js
import Hapi from 'hapi';
import { graphqlHapi } from 'apollo-server-hapi';
const HOST = 'localhost';
const PORT = 3000;
const { ApolloServer, gql } = require('apollo-server-hapi');
const Hapi = require('hapi');
async function StartServer() {
const server = new Hapi.server({
host: HOST,
port: PORT,
const server = new ApolloServer({ typeDefs, resolvers });
const app = new Hapi.server({
port: 4000
});
await server.register({
plugin: graphqlHapi,
options: {
path: '/graphql',
graphqlOptions: {
schema: myGraphQLSchema,
},
route: {
cors: true,
},
},
await server.applyMiddleware({
app,
});
try {
await server.start();
} catch (err) {
console.log(`Error while starting server: ${err.message}`);
}
await server.installSubscriptionHandlers(app.listener);
console.log(`Server running at: ${server.info.uri}`);
await app.start();
}
StartServer();
StartServer().catch(error => console.log(error));
```
### Koa
### Context
The context is created for each request. The following code snippet shows the creation of a context. The arguments are the `request`, the request, and `h`, the response toolkit.
```js
import koa from 'koa'; // koa@2
import koaRouter from 'koa-router'; // koa-router@next
import koaBody from 'koa-bodyparser'; // koa-bodyparser@next
import { graphqlKoa, graphiqlKoa } from 'apollo-server-koa';
const app = new koa();
const router = new koaRouter();
const PORT = 3000;
// koaBody is needed just for POST.
router.post('/graphql', koaBody(), graphqlKoa({ schema: myGraphQLSchema }));
router.get('/graphql', graphqlKoa({ schema: myGraphQLSchema }));
router.get('/graphiql', graphiqlKoa({ endpointURL: '/graphql' }));
app.use(router.routes());
app.use(router.allowedMethods());
app.listen(PORT);
```
### Restify
```js
import restify from 'restify';
import { graphqlRestify, graphiqlRestify } from 'apollo-server-restify';
const PORT = 3000;
const server = restify.createServer({
title: 'Apollo Server',
});
const graphQLOptions = { schema: myGraphQLSchema };
server.use(restify.plugins.bodyParser());
server.use(restify.plugins.queryParser());
server.post('/graphql', graphqlRestify(graphQLOptions));
server.get('/graphql', graphqlRestify(graphQLOptions));
server.get('/graphiql', graphiqlRestify({ endpointURL: '/graphql' }));
server.listen(PORT, () => console.log(`Listening on ${PORT}`));
new ApolloServer({
typeDefs,
resolvers,
context: async ({ request, h }) => {
return { ... };
},
})
```
### AWS Lambda
Lambda function should be run with [Node.js 4.3 or v6.1](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-using-old-runtime.html#nodejs-prog-model-runtime-support-policy). Requires an API Gateway with Lambda Proxy Integration.
Apollo Server can be run on Lambda and deployed with AWS Serverless Application Model (SAM). It requires an API Gateway with Lambda Proxy Integration.
```js
var server = require('apollo-server-lambda');
const { ApolloServer, gql } = require('apollo-server-lambda');
exports.handler = server.graphqlLambda({ schema: myGraphQLSchema });
```
// Construct a schema, using GraphQL schema language
const typeDefs = gql`
type Query {
hello: String
}
`;
### ZEIT Micro
Requires the [Micro](https://github.com/zeit/micro) module
```js
const server = require('apollo-server-micro');
module.exports = server.microGraphql({ schema: myGraphQLSchema });
```
### Adonis Framework
```js
// start/routes.js
const { graphqlAdonis } = require('apollo-server-adonis');
const Route = use('Route');
Route.post('/graphql', graphqlAdonis({ schema: myGraphQLSchema }));
Route.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](https://github.com/apollographql/apollo-tracing)
- **fieldResolver**: a custom default field resolver
- **debug**: a boolean that will print additional debug logging if execution errors occur
- **cacheControl**: when set to true, enable built-in support for Apollo Cache Control
All options except for `schema` are optional.
### Whitelisting
The `formatParams` function can be used in combination with the `OperationStore` to enable whitelisting.
```js
const store = new OperationStore(Schema);
store.put('query testquery{ testString }');
graphqlOptions = {
schema: Schema,
formatParams(params) {
params['parsedQuery'] = store.get(params.operationName);
delete params['queryString']; // Or throw if this is provided.
return params;
// Provide resolver functions for your schema fields
const resolvers = {
Query: {
hello: () => 'Hello world!',
},
};
```
## Comparison with `express-graphql`
const server = new ApolloServer({ typeDefs, resolvers });
Both Apollo Server and [`express-graphql`](https://github.com/graphql/express-graphql) are GraphQL servers for Node.js, built on top of the [`graphql-js` reference implementation](https://github.com/graphql/graphql-js), 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](https://github.com/graphql/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:
```js
import express from 'express';
import bodyParser from 'body-parser';
import { graphqlExpress } from 'apollo-server-express';
const myGraphQLSchema = // ... define or import your schema here!
const helperMiddleware = [
bodyParser.json(),
bodyParser.text({ type: 'application/graphql' }),
(req, res, next) => {
if (req.is('application/graphql')) {
req.body = { query: req.body };
}
next();
}
];
express()
.use('/graphql', ...helperMiddleware, graphqlExpress({ schema: myGraphQLSchema }))
  .listen(3000);
exports.graphqlHandler = server.createHandler();
```
## Apollo Server Development
@ -291,7 +208,7 @@ If you want to develop Apollo Server locally you must follow the following instr
git clone https://github.com/[your-user]/apollo-server
cd apollo-server
npm install
cd packages/apollo-server-<variant>/
cd packages/apollo-server-<integration>/
npm link
```
@ -299,5 +216,5 @@ npm link
```
cd ~/myApp
npm link apollo-server-<variant>
npm link apollo-server-<integration>
```

3
docs/source/essentials/server.md
View file

@ -111,8 +111,6 @@ Your server itself is hosted at http://localhost:4000/graphql. This would be the
Depending on whether we are creating a new application or an existing application, the steps will vary slightly since Apollo Server must adapt to the semantics of existing servers (e.g. Express, Hapi, etc.)
Both import methods will use the `apollo-server` module we installed in the previous step, but existing applications will also install a middleware package which corresponds to the desired HTTP server.
<h3 id="middleware">Middleware</h3>
Existing applications generally already have middleware in place and Apollo Server works along with those middleware. To integrate with Apollo Server, we'll pass it into the `server.applyMiddleware` method as `app` to add the Apollo Server's middleware.
@ -136,6 +134,7 @@ app.listen({ port: 4000 }, () =>
)
```
Hapi follows the same pattern with `apollo-server-express` replaced with `apollo-server-hapi` and `app` replaced with Hapi server. `applyMiddleware` registers plugins, so it should be called with `await`.
<h3 id="serverless">Serverless</h3>

2
packages/apollo-server-core/src/ApolloServer.ts
View file

@ -69,7 +69,7 @@ export class ApolloServerBase {
// set by installSubscriptionHandlers.
private subscriptionServer?: SubscriptionServer;
// The constructor should be universal across all environments. All environment specific behavior should be set in an exported registerServer or in by overriding listen
// The constructor should be universal across all environments. All environment specific behavior should be set by adding or overriding methods
constructor(config: Config) {
if (!config) throw new Error('ApolloServer requires options.');
const {

32
packages/apollo-server-express/README.md
View file

@ -8,15 +8,14 @@ description: Setting up Apollo Server with Express.js or Connect
This is the Express and Connect integration of GraphQL Server. Apollo Server is a community-maintained open-source GraphQL server that works with many Node.js HTTP server frameworks. [Read the docs](https://www.apollographql.com/docs/apollo-server/). [Read the CHANGELOG.](https://github.com/apollographql/apollo-server/blob/master/CHANGELOG.md)
```sh
npm install apollo-server@beta apollo-server-express@beta
npm install apollo-server-express@rc
```
## Express
```js
const express = require('express');
const { registerServer } = require('apollo-server-express');
const { ApolloServer, gql } = require('apollo-server');
const { ApolloServer, gql } = require('apollo-server-express');
// Construct a schema, using GraphQL schema language
const typeDefs = gql`
@ -35,19 +34,19 @@ const resolvers = {
const server = new ApolloServer({ typeDefs, resolvers });
const app = express();
registerServer({ server, app });
server.applyMiddleware({ app });
server.listen().then(({ url }) => {
console.log(`🚀 Server ready at ${url}`);
});
app.listen({ port: 4000 }, () =>
console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`)
)
```
## Connect
```js
import connect from 'connect';
const { registerServer } = require('apollo-server-express');
const { ApolloServer, gql } = require('apollo-server');
const connect = require('connect');
const { ApolloServer, gql } = require('apollo-server-express');
const query = require('qs-middleware');
// Construct a schema, using GraphQL schema language
const typeDefs = gql`
@ -66,13 +65,18 @@ const resolvers = {
const server = new ApolloServer({ typeDefs, resolvers });
const app = connect();
registerServer({ server, app });
const path = '/graphql';
server.listen().then(({ url }) => {
console.log(`🚀 Server ready at ${url}`);
});
server.use(query());
server.applyMiddleware({ app, path });
app.listen({ port: 4000 }, () =>
console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`)
)
```
> Note; `qs-middleware` is only required if running outside of Meteor
## Principles
GraphQL Server is built with the following principles in mind:

57
packages/apollo-server-hapi/README.md
View file

@ -8,74 +8,31 @@ description: Setting up Apollo Server with Hapi
This is the Hapi integration of Apollo Server. Apollo Server is a community-maintained open-source Apollo Server that works with many Node.js HTTP server frameworks. [Read the docs](https://www.apollographql.com/docs/apollo-server/). [Read the CHANGELOG.](https://github.com/apollographql/apollo-server/blob/master/CHANGELOG.md)
```sh
npm install apollo-server-hapi@beta
npm install apollo-server-hapi@rc
```
## Usage
After constructing Apollo server, a hapi server can be enabled with a call to `registerServer`. Ensure that `autoListen` is set to false in the `Hapi.server` constructor.
The code below requires Hapi 17 or higher.
```js
const { registerServer, ApolloServer, gql } = require('apollo-server-hapi');
const HOST = 'localhost';
const typeDefs = gql`
type Query {
hello: String
}
`;
const resolvers = {
Query: {
hello: () => 'hello',
},
}
async function StartServer() {
const server = new ApolloServer({ typeDefs, resolvers });
await registerServer({
server,
//Hapi Server constructor options
options: {
host: HOST,
},
});
server.listen().then(({ url }) => {
console.log(`🚀 Server ready at ${url}`);
});
}
StartServer().catch(error => console.log(error));
```
For more advanced use cases or migrating from 1.x, a Hapi server can be constructed and passed into `registerServer`.
```js
const { ApolloServer, gql, registerServer } = require('apollo-server-hapi');
const { ApolloServer, gql } = require('apollo-server-hapi');
const Hapi = require('hapi');
async function StartServer() {
const server = new ApolloServer({ typeDefs, resolvers });
const app = new Hapi.server({
//autoListen must be set to false, since Apollo Server will setup the listener
autoListen: false,
host: HOST,
port: 4000
});
await registerServer({
server,
await server.applyMiddleware({
app,
});
server.listen().then(({ url }) => {
console.log(`🚀 Server ready at ${url}`);
});
await server.installSubscriptionHandlers(app.listener);
await app.start();
}
StartServer().catch(error => console.log(error));

2
packages/apollo-server-lambda/README.md
View file

@ -5,7 +5,7 @@ description: Setting up Apollo Server with AWS Lambda
[![npm version](https://badge.fury.io/js/apollo-server-lambda.svg)](https://badge.fury.io/js/apollo-server-lambda) [![Build Status](https://circleci.com/gh/apollographql/apollo-server.svg?style=svg)](https://circleci.com/gh/apollographql/apollo-server) [![Coverage Status](https://coveralls.io/repos/github/apollographql/apollo-server/badge.svg?branch=master)](https://coveralls.io/github/apollographql/apollo-server?branch=master) [![Get on Slack](https://img.shields.io/badge/slack-join-orange.svg)](https://www.apollographql.com/#slack)
This is the AWS Lambda integration of GraphQL Server. Apollo Server is a community-maintained open-source GraphQL server that works with many Node.js HTTP server frameworks. [Read the docs](https://www.apollographql.com/docs/apollo-server/). [Read the CHANGELOG](https://github.com/apollographql/apollo-server/blob/master/CHANGELOG.md).
This is the AWS Lambda integration of GraphQL Server. Apollo Server is a community-maintained open-source GraphQL server that works with many Node.js HTTP server frameworks. [Read the docs](https://www.apollographql.com/docs/apollo-server/v2). [Read the CHANGELOG](https://github.com/apollographql/apollo-server/blob/master/CHANGELOG.md).
```sh
npm install apollo-server-lambda@rc

2
packages/apollo-server/src/index.ts
View file

@ -1,5 +1,5 @@
// Note: express is only used if you use the ApolloServer.listen API to create
// an express app for you instead of registerServer (which you might not even
// an express app for you instead of applyMiddleware (which you might not even
// use with express). The dependency is unused otherwise, so don't worry if
// you're not using express or your version doesn't quite match up.
import * as express from 'express';