Atomic Object’s blog on everything we find fascinating.

GraphQL + Apollo – Part 2: Building a Server

In this series, we are taking a dive into GraphQL through the lens of the Apollo toolchain. Part 1 of the series explains some core concepts of GraphQL and introduces Apollo as a GraphQL solution. In this post, we will take a closer look at building a GraphQL server with Apollo tools. Part 3 will take a look at the Apollo Client libraries and implement an example client.

What is Apollo Server?

Apollo Server is essentially a set of tools which are useful for building a GraphQL Server. The package name that includes these server tools is graphql-tools, which is created and maintained by the Apollo community. Graphql-tools are a set of tools which enable production-ready GraphQL.js schema building using the GraphQL schema language, rather than using the (rather clunky) GraphQL.js type constructors directly.

Essentially, Apollo Server is a thin API and routing layer for your application. It will, at a high level:

Receive incoming GraphQL queries/mutations and map to schema

Resolve and validate input types

Map query/mutation to root resolver to begin resolving the request

Resolve and validate types for return data

Defining the Schema

The core of a GraphQL Server is the schema. The schema defines types and their relationships with each other, along with the specific queries and mutations which can be executed. Apollo Server uses the GraphQL schema language notation, which it then compiles to a GraphQL.js schema.

This schema defines three root queries: personWithName, guys, and girls, all of which return either a single Person or a Person array. We also have a Person type which defines several different fields on that object.

Setting up Resolvers

Resolvers are the glue between the schema and your data. Apollo uses them to figure out how to respond to a query and resolve the incoming or return types. Every query and mutation requires a resolver function, and each field in every type can have a resolver.

Apollo will continue to invoke the chain of resolvers until it reaches a scalar type (i.e. String, Int, Float, Boolean). So, we should define a few root resolvers for the queries:

So there we have it: three query resolvers. For the sake of keeping this example simple, I added a static array of fake people and a function findBy which simulates sending a query to a database, returning a promise.

When a promise is returned from a resolver function, Apollo will automatically wait for the promise to resolve or reject. If the promise resolves successfully, Apollo will try to use that data to resolve the return type of the query–in our case, a Person type.

Since name, age and gender are all scalar types (String) and the name in the data matches the name in the type definition, there is no need to define a resolver for those fields.

However, let’s say we want to do some conversion on the name–like capitalize the name–and then return the capitalized string. To implement this, we just need to define a name resolver that capitalizes the input name. We also need a resolver for the height field, since this field takes an argument. Given the source object (as returned from the root resolver) and the field arguments, this field resolver must convert the value to the desired units.

There is one additional piece of code that you need to write to actually “glue” the schema to its resolvers. You must call makeExecutableSchema and pass in the schema(s) and an object containing all resolvers.

Connecting to Express

Now that we have a functional schema and “backend,” we need to hook into a server framework such as Express. Apollo has a really nice integration with Express (along with a few others mentioned earlier), where all you really need to do is define the GraphQL endpoint and pass in your schema. Below is a simple example: