How to use apollo-server: install and run a GraphQL API

What apollo-server does and who it is for

Apollo Server is a library, not a hosted service. You run it inside your own Node.js project. It plugs into common Node web frameworks, so clients can send GraphQL queries over HTTP to the endpoint your app provides. The project describes itself as spec-compliant and production ready, and as built for a schema-first way of working.

It fits best if you want to add a GraphQL API to an existing Express, Koa or Hapi app, or if your team prefers to define the schema first and then implement resolvers. It is not a good fit if you only need a REST API or a static site, or if your project must use a non-Node.js server language.

• Licence: MIT
• Language: TypeScript
• Runs on: Node.js
• Frameworks named in the project description: Express, Connect, Hapi, Koa, and more

Install apollo-server on Node.js

You need Node.js installed. The project's README gives the package-manager install command below, which installs the server package along with graphql.

Define a schema and resolvers

A GraphQL schema describes the types and fields your API exposes. Resolvers are functions that return the data for each field. In a schema-first workflow you write the schema, then implement the resolvers that match it.

Keep the schema as the contract between your front end and back end. Each field a client can request should have a resolver that returns its value, whether that data comes from a database, another service or memory.

• Write the schema describing your types and queries.
• Write a resolver function for each field that needs to return data.
• Pass the schema and resolvers to the server when you create it.

Connect the server to an HTTP framework

apollo-server is designed to plug into Node web frameworks such as Express, Koa and Hapi. Once connected, clients send GraphQL queries to the HTTP route your framework serves. Check the project's documentation at https://www.apollographql.com/docs/apollo-server/ for the integration code for your chosen framework, since the README excerpt used for this guide does not include it.

Common mistakes and troubleshooting

Most early problems come from setup rather than the library itself. If the install fails, confirm that Node.js is installed and that you ran the install command inside your project folder. If queries return nothing, check that every field a client requests has a matching resolver in your schema.

Remember that apollo-server runs only on Node.js. If you try to use it from a different server language, it will not work for that part of the stack.

• Install failed: confirm Node.js is present and run npm from the project folder.
• Field returns null or nothing: check that a resolver exists for that field.
• Wrong runtime: the library runs only on Node.js.