Apollo integration with Node + Express
In this article, we’ll show you how to start developing an application’s backend with architecture managed by GraphQL. To do this, you should know your way around JavaScript and have some knowledge of the command-line interface. You will also need to have a recent version of Node installed (8 or above).
This tutorial will help you:
- Gain basic knowledge of GraphQL
- Define a GraphQL schema that represents the app’s data structure
- Run an instance of Apollo Server with Express to execute queries that match your schema
Brief introduction
Nowadays, every software requires a service to obtain data from. This data is usually obtained from an application programming interface or API. After Roy Fielding developed the REST concept in 2000, APIs became one of the cornerstones of programming as they allow for client-server communication. This still remains one of the most popular software development architectures today.
As you may know, the tech industry advances quite rapidly and its community is constantly looking for new technologies and improvements. API management was no exception and, thanks to Facebook, GraphQL was born in 2012.
GraphQL provides a specification of a query language, which means it is neither a piece of software or a package, nor something you can download and use, but a document that explains how this language works and is used. Various companies worked on implementations of GraphQL when it became open source back in 2015. One of them, and the one we’ll look at in this tutorial, is Apollo GraphQL.
What is Apollo Server?
According to Apollo’s official website:
“Apollo Server is an open-source, spec-compliant GraphQL server that’s compatible with any GraphQL client, including Apollo Client. It’s the best way to build a production-ready, self-documenting GraphQL API that can use data from any source.”
In this particular, we’ll be using Apollo Server as an add-on for our application’s Express middleware.
Let’s jump into the code
You can find a detailed step-by-step guide to get your GraphQL API running using Apollo in Apollo Server’s documentation, but here is an overview of the basics:
-
Creating a project
First of all, you’ll need to create a directory for a new project from your development directory of choice and cd into it using the command line:
Link: script
Then, you’ll start a new Node.js project using npm (or whatever package manager you prefer).
Link: script
Now your project directory contains a package.json file.
-
Installing dependencies
You will need three top-level dependencies for your application to run:
- apollo-server-express: the Express integration that comes with GraphQL Server.
- graphql: the library you’ll use to build a GraphQL schema and execute queries.
- express: in charge of server-side logic for web apps.
In order to install these dependendencies, you will need to run the following command:
Link: script
To make things easier, create an empty index.js file in your project’s root directory which will contain all your code.
-
Defining your GraphQL schema
Every GraphQL server uses a schema in order to define the data structure for clients to query. Here, we’ll see how a server that queries a collection of books by title and author can be created.
We’ll start by opening index.js in your editor of choice and then pasting the following code:
Link: script
The snippet above defines a simple GraphQL schema. This will execute a query named “books”, to which the server will respond with an array of zero or more books.
-
Defining your data set
Once you’ve defined the structure of the data, you’ll create some actual data. Apollo Server can retrieve data from any source you connect to, which includes databases, static object storage services, REST APIs, or even other GraphQL servers. That said, in this example, we’ll hardcode some dummy data to keep things simple.
You will need to add the following at the end of the index.js file:
Link: script
Keep in mind that each object in the array matches the structure of the Book type defined in our schema.
-
Defining a resolver
Great job so far! Your data set is defined, but Apollo Server is not yet able to use that data set on its own when it’s executing a query. This is why you will need to create a resolver.
Apollo Server uses resolvers to determine to fetch the data associated with a specific type. Since this Book array is hardcoded, the relevant resolver will be quite simple.
You will need to add the following at the end of the index.js file:
Link: script
-
Creating a server with Express JS.
We now have the initial schema with the relevant resolvers. All that’s left is to provide this information to Apollo Server, which can be done using Express middleware.
First, you’ll create an Apollo Server instance that will serve as middleware to an Express HTTP instance using server.applyMiddleware({ app }). Then, add the following at the end of the index.js file.
Link: script
-
Starting the server
We’re almost done! Now we can run the server and start executing queries. You will need to run the command below from the project’s root directory:
Link: script
This is the output that should appear: Server ready at http://localhost:4000/.
That’s it! You got it!
Final thoughts
Today we learned about Apollo Server and how to define a schema with its corresponding resolvers. We also set up a GraphQL server using Express.js as middleware.
Using Express has a few advantages, one of which is being able to serve both REST and GraphQL at the same time. Also, serving a GraphQL server within Express maintains your ability to use the middleware for common problems like security, authentication and others.
However, we have to say that apollo-server, the standalone GraphQL server, is faster than apollo-server-express.
That said, we believe that, overall, using Express with Apollo Server is a good practice and the tradeoff is more than positive.
