Where do you keep your dad jokes? In a dadabase of course! Let’s imagine that you are a site maintainer for the world’s best dad joke database. Your app communicates with the database using a REST API that allows you to retrieve jokes and post ratings for those jokes. Visitors to your site can rate each joke they see via a simple user interface.
Recently you heard of a fancy new technology called GraphQL that provides the flexibility to request only the data that you need using a single API endpoint. It sounds neat, and you’d like to start using it in your app. But, you’d really prefer not to make any breaking changes to the existing REST API. Is it possible to support both the REST API and the GraphQL API in your app? You’re about to find out!
In this article we’ll explore what it takes to implement a GraphQL API on top of an existing REST API. This strategy allows you to start using GraphQL in legacy portions of your app without breaking any existing contracts with functionality that may still rely on the original REST API.
The Initial Architecture
Our JSON file contains information for a few jokes as well as some ratings. It’s reproduced in full below:
JSON Server takes that file as a starting point for the database and then implements a REST API that includes support for GET, POST, PUT, PATCH, and DELETE requests. The magic of JSON Server is that using this API really does modify the underlying JSON file, so the database is fully interactive. JSON Server can be started directly from an npm script without any additional setup, but in order to provide a little more configuration and a dynamic port, we can instead write a few lines of code like so:
You can test out our mock database by cloning the repo for the API, running
npm install, and then running
npm start. If you navigate to http://localhost:3000/jokes you’ll see all of the jokes. Navigating to http://localhost:3000/ratings will display all the ratings.
Wonderful! We can run our app’s backend locally in the browser. Now let’s get our API hosted on Heroku. First, we need to install the Heroku CLI. After that, we can log in, create the app, push it to Heroku, and open the new app in our browser in four easy steps:
heroku login # logs in to your Heroku account heroku create dad-joke-dadabase-rest-api # creates the Heroku app git push heroku master # deploys the code to Heroku heroku open # opens the Heroku app on your machine
And look, now we have a publicly available API out on the web!
Building the User Interface
/jokes?_embed=ratings endpoint. The second makes a POST request to the
/ratings endpoint to submit a new rating for each joke you rate.
Setting Up Apollo Server
So, that’s the existing app architecture: a simple front-end that interacts with the database via a REST API. Now how can we begin using GraphQL? We’ll start by installing
apollo-server-express, which is a package that allows us to use Apollo Server with Express. We’ll also install the
apollo-datasource-rest package to help us integrate the REST API with Apollo Server. Then we’ll configure the server by writing the following code:
As you can see, we configure Apollo Server with type definitions (
typeDefs contain the schema for our GraphQL API. In it, we’ll define types for our jokes and ratings as well as how to query and mutate them. The
resolvers tell the server how to handle various queries and mutations and how those link to our data sources. And finally, the
dataSources outline how the GraphQL API relates to the REST API.
Here are the type definitions for the
Rating types and how to query and mutate them:
The jokes data source defines methods for calling the original REST API endpoint to create, read, update, and delete jokes from the database:
The ratings data source looks nearly identical, but with “rating” substituted for “joke” in every instance. (refer to the GitHub repo if you’d like to see the code for this.)
Finally, we set up our resolvers to show how to use the data sources:
With that, we have everything in place we need in order to start using our GraphQL API through Apollo Server. To get our new front-end and GraphQL API hosted on Heroku, we’ll create and deploy a second app like so:
heroku create dad-joke-dadabase # creates the Heroku app git push heroku master # deploys the code to Heroku heroku open # opens the Heroku app on your machine
Replacing the Endpoint to Fetch Jokes
You’ll recall that we have two endpoints used by the front-end: one to fetch jokes and one to post ratings. Let’s swap out the REST API for our GraphQL API when we fetch the jokes. The code previously looked like this:
Now to use the GraphQL endpoint, we can write this instead:
We can run the app locally now and verify that the user experience still works properly. In fact, from the user’s point of view, nothing has changed at all. But if you look at the network requests in your browser’s developer tools, you’ll see that we’re now fetching our jokes from the
/graphql endpoint. Amazing!
Replacing the Endpoint to Submit Ratings
One API down, one to go! Let’s swap out the ratings submission functionality now. The code to post a new joke rating previously looked like this:
To use our GraphQL API, we’ll now use the following:
A quick test gives us some promising results. Once again, the user experience remains unchanged, but now we’re fully using the
/graphql endpoint for both our requests!
We did it! We successfully wrote a GraphQL API endpoint on top of an existing REST API. This allows us to use GraphQL to our heart’s content without breaking existing functionality and without modifying the original REST API. Now we can deprecate the REST API or get rid of it completely at a later date.
While our dad joke database is entirely fictional, nearly every technology company that existed prior to GraphQL’s release in 2015 will find themselves in this same position of migrating to GraphQL if and when they choose to do so. The good news is that Apollo Server is flexible enough to pull data from a variety of sources, including existing REST API endpoints.