What is apollo-server?
Apollo Server is a community-driven, open-source GraphQL server that works with any GraphQL schema. It is designed to be a self-contained GraphQL server that can be used with any Node.js HTTP server framework, such as Express, Koa, or Hapi.
What are apollo-server's main functionalities?
Creating a Basic GraphQL Server
This code sets up a basic Apollo Server with a single query type 'hello' that returns a string 'Hello world!'.
const { ApolloServer, gql } = require('apollo-server');
const typeDefs = gql`
type Query {
hello: String
}
`;
const resolvers = {
Query: {
hello: () => 'Hello world!',
},
};
const server = new ApolloServer({ typeDefs, resolvers });
server.listen().then(({ url }) => {
console.log(`๐ Server ready at ${url}`);
});
Integrating with Express
This code demonstrates how to integrate Apollo Server with an Express application.
const express = require('express');
const { ApolloServer, gql } = require('apollo-server-express');
const typeDefs = gql`
type Query {
hello: String
}
`;
const resolvers = {
Query: {
hello: () => 'Hello world!',
},
};
const server = new ApolloServer({ typeDefs, resolvers });
const app = express();
server.applyMiddleware({ app });
app.listen({ port: 4000 }, () =>
console.log(`๐ Server ready at http://localhost:4000${server.graphqlPath}`)
);
Adding Middleware for Authentication
This code adds middleware to the Apollo Server for authentication by checking the authorization header and adding the user to the context.
const { ApolloServer, gql } = require('apollo-server');
const typeDefs = gql`
type Query {
hello: String
}
`;
const resolvers = {
Query: {
hello: (parent, args, context) => {
if (!context.user) throw new Error('Not authenticated');
return 'Hello world!';
},
},
};
const getUser = (token) => {
// Mock function to get user from token
return token ? { id: 1, name: 'John Doe' } : null;
};
const server = new ApolloServer({
typeDefs,
resolvers,
context: ({ req }) => {
const token = req.headers.authorization || '';
const user = getUser(token);
return { user };
},
});
server.listen().then(({ url }) => {
console.log(`๐ Server ready at ${url}`);
});
Other packages similar to apollo-server
express-graphql
express-graphql is a middleware for Express that allows you to mount a GraphQL API server. It is simpler and more lightweight compared to Apollo Server, but it lacks some of the advanced features and integrations that Apollo Server offers.
graphql-yoga
graphql-yoga is a fully-featured GraphQL server that is based on Apollo Server and Express. It provides a more opinionated setup with built-in support for features like subscriptions, file uploads, and more. It is easier to get started with but may be less flexible than Apollo Server.
mercurius
mercurius is a GraphQL adapter for Fastify, a fast and low-overhead web framework for Node.js. It offers high performance and integrates well with the Fastify ecosystem, but it may not have as many built-in features as Apollo Server.
A TypeScript GraphQL Server for Express, Koa, Hapi, Lambda, and more.
Apollo Server is a community-maintained open-source GraphQL server. It works with many Node.js HTTP server frameworks, or can run on its own with a built-in Express server. Apollo Server works with any GraphQL schema built with GraphQL.js--or define a schema's type definitions using schema definition language (SDL).
Read the documentation for information on getting started and many other use cases and follow the CHANGELOG for updates.
Principles
Apollo Server is built with the following principles in mind:
- By the community, for the community: Its development is driven by the needs of developers.
- Simplicity: By keeping things simple, it is more secure and easier to implement and contribute.
- Performance: It is well-tested and production-ready.
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
To get started with Apollo Server:
- Install with
npm install apollo-server-<integration> graphql
- Write a GraphQL schema
- Use one of the following snippets
There are two ways to install Apollo Server:
- Standalone: For applications that do not require an existing web framework, use the
apollo-server
package. - Integrations: For applications with a web framework (e.g.
express
, koa
, hapi
, etc.), use the appropriate Apollo Server integration package.
For more info, please refer to the Apollo Server docs.
Installation: Standalone
In a new project, install the apollo-server
and graphql
dependencies using:
npm install apollo-server graphql
Then, create an index.js
which defines the schema and its functionality (i.e. resolvers):
const { ApolloServer, gql } = require('apollo-server');
const typeDefs = gql`
type Query {
"A simple type for getting started!"
hello: String
}
`;
const resolvers = {
Query: {
hello: () => 'world',
},
};
const server = new ApolloServer({
typeDefs,
resolvers,
});
server.listen().then(({ url }) => {
console.log(`๐ Server ready at ${url}`);
});
Due to its human-readability, we recommend using schema-definition language (SDL) to define a GraphQL schema--a GraphQLSchema
object from graphql-js
can also be specified instead of typeDefs
and resolvers
using the schema
property:
const server = new ApolloServer({
schema: ...
});
Finally, start the server using node index.js
and go to the URL returned on the console.
For more details, check out the Apollo Server Getting Started guide and the fullstack tutorial.
For questions, the Apollo community forum is a great place to get help.
Installation: Integrations
While the standalone installation above can be used without making a decision about which web framework to use, the Apollo Server integration packages are paired with specific web frameworks (e.g. Express, Koa, hapi).
The following web frameworks have Apollo Server integrations, and each of these linked integrations has its own installation instructions and examples on its package README.md
:
Context
A request context is available for each request. When context
is defined as a function, it will be called on each request and will receive an object containing a req
property, which represents the request itself.
By returning an object from the context
function, it will be available as the third positional parameter of the resolvers:
new ApolloServer({
typeDefs,
resolvers: {
Query: {
books: (parent, args, context, info) => {
console.log(context.myProperty);
return books;
},
}
},
context: async ({ req }) => {
return {
myProperty: true
};
},
})
Documentation
The Apollo Server documentation contains additional details on how to get started with GraphQL and Apollo Server.
The raw Markdown source of the documentation is available within the docs/
directory of this monorepo--to contribute, please use the Edit on GitHub buttons at the bottom of each page.
Development
If you wish to develop or contribute to Apollo Server, we suggest the following:
-
Fork this repository
-
Install Direnv (a tool that automatically sets up environment variables in project directories) or nvm. We use nvm to ensure we're running the expected version of Node (and we use Direnv to install and run nvm automatically).
-
Install the Apollo Server project on your computer
git clone https://github.com/[your-user]/apollo-server
cd apollo-server
direnv allow # sets up nvm for you; if you installed nvm yourself, try `nvm install` instead
npm install
npm test
- To run individual test files, run
npm run pretest && npx jest packages/apollo-server-foo/src/__tests__/bar.test.ts
. Note that you do need to re-compile TypeScript before each time you run a test, or changes across packages may not be picked up. Instead of running npm run pretest
from scratch before each test run, you can also run tsc --build tsconfig.json --watch
in another shell, or use the VSCode Run Build Task
to run that for you.
Are you stuck? Want to contribute? Come visit us in the Apollo community forum!
Maintainers
Who is Apollo?
Apollo builds open-source software and a graph platform to unify GraphQL across your apps and services. We help you ship faster with:
- Apollo Studio โ A free, end-to-end platform for managing your GraphQL lifecycle. Track your GraphQL schemas in a hosted registry to create a source of truth for everything in your graph. Studio provides an IDE (Apollo Explorer) so you can explore data, collaborate on queries, observe usage, and safely make schema changes.
- Apollo Federation โ The industry-standard open architecture for building a distributed graph. Use Apolloโs gateway to compose a unified graph from multiple subgraphs, determine a query plan, and route requests across your services.
- Apollo Client โ The most popular GraphQL client for the web. Apollo also builds and maintains Apollo iOS and Apollo Android.
- Apollo Server โ A production-ready JavaScript GraphQL server that connects to any microservice, API, or database. Compatible with all popular JavaScript frameworks and deployable in serverless environments.
Learn how to build with Apollo
Check out the Odyssey learning platform, the perfect place to start your GraphQL journey with videos and interactive code challenges. Join the Apollo Community to interact with and get technical help from the GraphQL community.