Apollo Server 0.2: GraphQL with Express, Connect, hapi or Koa
Jonas Helfer
Today, we’re proud to announce the release of Apollo Server 0.2!
Apollo Server is a GraphQL server for JavaScript, built by an open-source community of GraphQL enthusiasts. It uses GraphQL.js and works with all major Node.js server frameworks — Express, Connect, hapi and Koa.
The new Apollo Server is a major upgrade from version 0.1.0. Over the last few weeks, we re-wrote it from the ground up to be more simple, more modular and just generally more awesome. Our main goal was to build a fully-featured, yet simple GraphQL server that is production-ready and can evolve with the needs of the community.
Here’s a quick summary of what’s new compared to version 0.1 — more details below:
- Added support for hapi (thanks to Nick Nance!)
- Added support for Koa (thanks to @HriBB!)
- Rewritten from scratch in TypeScript
- Schema generation was moved to a separate repo — graphql-tools
- GraphiQL is served from a separate path
- Now exposes the core functions to allow for easy extension
- Added built-in support for query batching
- Added built-in support for stored queries
In addition to all of that, we also updated the docs and added many more code snippets to make it even easier to get started.
Why we re-wrote Apollo Server
The first version of Apollo Server was little more than a set of tools for generating GraphQL schemas, wrapped around express-graphql. While that was quite useful for demo purposes, it became clear that bundling a GraphQL server together with a set of tools for generating schemas wasn’t the right approach in the long term. In addition to splitting the schema tools into a separate project, we also wanted add some more usage/production oriented features: hapi and Koa support, batching and query whitelisting. Finally, we also wanted to make the project more maintainable by using TypeScript. That’s why we decided to re-write Apollo Server from the ground up.
The new features
1. Support for hapi and Koa
Everyone has their preference when it comes to Node.js server frameworks. Now that Apollo Server supports Express, Connect, hapi and Koa, the choice is completely up to you.
The following code snippet shows how to use Apollo Server with hapi:
import hapi from 'hapi';
import graphql from 'graphql';
import { ApolloHAPI } from 'apollo-server';
const myGraphQLSchema = new graphql.GraphQLSchema({
// define your schema in GraphQL.js syntax here ...
});
const server = new hapi.Server();
const HOST = 'localhost';
const PORT = 3000;
server.connection({
host: HOST,
port: PORT,
});
server.register({
register: new ApolloHAPI(),
options: { schema: myGraphQLSchema },
routes: { prefix: '/graphql' },2. Typings
With the complete re-write in TypeScript, you now get the benefits of having typings for Apollo Server, which makes it really nice to use in your other TypeScript projects. For a complete example, check out the swapi-apollo project by Nick Nance.
3. Simplified & modular codebase
To make Apollo Server easy to use and modify, we focused on simplicity and modularity. First, we made a small core, which is used by the Express, Connect, hapi and Koa integrations. To keep the core as simple as possible, we split other functionality, such as GraphiQL and stored queries, into a separate module. Finally, we removed support for defining GraphQL schemas in schema language and moved it to an entirely separate npm module — graphql-tools.
Apollo Server exposes the core functionality and modules, making it really easy to add functionality or extend it for use in other frameworks.
4. Query Batching
Query Batching is a feature we recently introduced in Apollo Client, but it involved merging multiple queries into a single one, which made the queries sent to the server hard to read. Now that Apollo Server supports query batching as a top-level feature, you can send multiple queries in one request without merging them, which makes debugging batched queries a lot easier.
5. Stored Queries, aka query whitelisting
Stored Queries is a feature that lets you define and validate queries ahead of time, so that when clients make requests they only have to send the name of the query along with variables. This not only saves bandwidth, but is also a way for you to secure your server by limiting the queries that clients can make.
Here’s an example of how to use query whitelisting:
import express from 'express';
import { apolloExpress, OperationStore } from 'apollo-server';
import Schema from './schema';
const PORT = 3000;
const store = new OperationStore(Schema);
store.put('query testquery{ testString }');
const app = express();
const options = {
schema: Schema,
formatParams(params) {
params['query'] = store.get(params.operationName);
if (!params['query']){
throw new Error(`Only whitelisted queries are allowed. No query stored for ${params.operationName}`);
}
return params;
}
};
app.use('/graphql', apolloExpress(options));
app.listen(PORT);Of course, you can also read the queries from a file on startup or expose an API on your server to add queries during runtime.
What’s next for Apollo Server?
Apollo Server was heavily inspired by the express-graphql reference implementation. Apart from the fact that Apollo Server supports hapi and Koa, while express-graphql does not, we also think that Apollo Server is more modular and easier to understand, making it easier for contributors to add new features.
Rather than seeing Apollo Server and express-graphql as competing alternatives, we think that they both have distinct roles in the GraphQL ecosystem. While express-graphql is intended to be a simple reference implementation of currently established standards, Apollo Server is built for production users and can evolve quickly with the needs of the community. This means it can serve as a proving ground for new concepts and ideas in the GraphQL ecosystem. Over time, express-graphql could adopt those features of Apollo Server which have proven themselves in practice.
The features in this release were driven by input and contributions from several community members interested in improving the production-readiness of GraphQL. Going forward, we will keep improving Apollo Server based on what the community of production GraphQL users need.
If you’re using GraphQL on Node.js, check out Apollo Server and join the contributor community by filing an issue or submitting a pull request!
Many thanks to Nick Nance, James Baxley III, Ian MacLeod, @HriBB for their contributions to Apollo Server 0.2!
