Using an existing REST API we'll learn how to create a GraphQL API around our existing services instead of a complete rewrite of our API.
Introduction
GraphQL is a fun service to consume on the client-side. With its documentation, playground, and state management options such as relay or apollo, developer experience has been a blast for myself and my co-workers. There is a common misconception that you can use either REST OR GraphQL, but not both. You can have both! When I was learning I thought it was all in GraphQL or all in REST. To learn more about the difference between these services visit Understanding GraphQL through REST. Many of us are in a situation where we have an existing REST API that we don't want to completely abandon to start to try out GraphQL.
By the end, you'll have a GraphQL API leveraging a REST API of your choice in JavaScript. For the purpose of quickness I'll be utilizing the Covid Act Now API, but feel free to sub out your own REST API and models. If you will be using the same API I would recommend obtaining your API key now. It's immediate so no wait time needed! Let's get started.
Building your API
We'll be setting up JavaScript with a hello world script, converting that to a GraphQL hello world endpoint, adding a REST data source, and making a relationship to combine API calls.
Project Setup
Project setup has some optional steps such as using nodemon to reload our app for us, and dotenv to load environment variables. This would be where you would add in the tools you prefer to work with in JavaScript.
Create Project
mkdir covid-graphql
Initialize an npm Package
npm init -y
Create a Source Directory and an index.js File
touch src/index.js
Add a hello world Log to index.js
console.log("hello world")
Open package.json and Add dev and start Scripts
"dev": "nodemon src/index.js --watch src/",
"start": "node src/index.js"
-
devutilizes nodemon to watch for any changes in thesrcdirectory. -
startusing node (lighter than nodemon in production).
Run npm run dev in Terminal
Making sure we're up and running and don't need to restart our app for every change going forward.
hello world
Take it easy on me if you thought this was pointless. It will help someone.
Install Dependencies
npm install apollo-server apollo-datasource-rest dotenv
apollo-server
Used to spin up an express server.
apollo-datasource-rest
Used to take advantage of caching and other class-based inheritance around REST sources.
dotenv
Used to pass in environment variables.
nodemon
Used in development mode so you don't need to restart your app every time there is a file change.
Create a Hello World Schema
This schema file will be where we define what we can do with our GraphQL API.
touch src/schema.js
// schema.js
const { gql } = require("apollo-server")
const typeDefs = gql`
type Query {
hello: String
}
`
module.exports = typeDefs
What we're saying in the typeDefs object is when we go to query in our graphQL API, we're only able to query hello and we expect a nullable String return type. In order to make that response not nullable we would just add an exclamation point to the end like so hello: String!.
Build Apollo Server
// src/index.js
require("dotenv").config()
const { ApolloServer } = require("apollo-server")
const typeDefs = require("./schema")
const server = new ApolloServer({ typeDefs })
const port = process.env.port || 9000
server.listen(port).then(() => {
console.log(`server running š http://localhost:${port}`)
})
Inspect at http://localhost:9000 to see your schema defined. If you happen to try querying hello you will realize the response is null. We need to still define our resolver response.
Create Resolver for hello
Resolvers are where the actual work gets done. The schema sets the limitations of the API in terms of what the clients can do. Actually doing that work is the job of the resolver. Similar to the query and mutation explanation in my previous posts, we will return Query and Mutation if needed. Under query, we now add in our hello resolver to return hello world.
touch src/resolvers.js
module.exports = {
Query: {
hello: () => {
return "hello world"
}
}
}
Add Resolver to src/index.js apollo-server Declaration
const resolvers = require("./resolvers")
const server = new ApolloServer({ typeDefs, resolvers })
At this point, when you query hello you should get your expected response.
Hooking Up a REST Source
Here we're going to build a REST Data source class that will be able to be utilized in our resolver to leverage some actual results.
Create REST Data Source
mkdir src/datasources
touch src/datasources/CovidActNowAPI.js
const { RESTDataSource } = require("apollo-datasource-rest")
class CovidActNowAPI extends RESTDataSource {
constructor() {
super()
this.baseURL = "https://api.covidactnow.org/v2/"
}
}
module.exports = CovidActNowAPI
All we really need to do here is extend RESTDataSource to get access to in-memory caching, HTTP helper functions, and pagination. To learn more visit apollo-datasource-rest.
Create .env File and Add-in API Key from Introduction
Hopefully, you've stowed away the key after obtaining your api key from the Covid Act Now API.
touch .env
COVID_ACT_NOW=YOUR_KEY_HERE
Add Some Methods to Get States and Counties in CovidActNowAPI Class
Taking a look at the Covid Act Now API documentation we can see JSON response can be hit at our baseURL(https://api.covidactnow.org/v2/) plus states for all US states, state/OH for an individual US state such as Ohio, counties for all US counties, and county/39001 for an individual county by fips plus our API key as a parameter. There is also an optional .timeseries we can append to include an array of values for things like metrics and actual figures. For getting a list of states or counties I'm choosing to avoid this as it's a much larger payload, but I am enabling the time series for individual US states and counties. Using this we can create functions to interact with the REST service now.
async getAllStates() {
const response = await this.get(`states.json?apiKey=${process.env.COVID_ACT_NOW}`);
return response || [];
}
async getState(stateCode) {
const response = await this.get(
`state/${stateCode}.timeseries.json?apiKey=${process.env.COVID_ACT_NOW}`
);
return response;
}
async getAllCounties() {
const response = await this.get(`counties.json?apiKey=${process.env.COVID_ACT_NOW}`);
return response || [];
}
async getCounty(fips) {
const response = await this.get(
`county/${fips}.timeseries.json?apiKey=${process.env.COVID_ACT_NOW}`
);
return response;
}
Add Data Source to apollo-graphql Server
// index.js
const CovidActNowAPI = require("./datasources/CovidActNowAPI")
const server = new ApolloServer({
dataSources: () => ({
covidApi: new CovidActNowAPI()
}),
typeDefs,
resolvers
})
Update Schema to Reflect States and Counties as Queries
This should be your most time-consuming part. Relative to the Covid Act Now API they have a convenient models section that will show you some of the subcategory types you'll need to recreate to tell consumers of this API what is possible. My process here for any API is to just look through the JSON response and make sure all the data I want available is covered. Every nested object needs a type in your schema to be recognized. If you don't need it, don't make a type for it and it's ignored š You can also reference apollo docs - build a schema to look at any syntax here such as the non-nullable (!), input parameters on a query or mutation (county(fips: String!): County), or array response([County]).
const typeDefs = gql`
type Query {
counties: [County!]!
county(fips: String!): County
states: [State!]!
state(stateCode: String!): State
}
type County {
fips: String!
country: String!
state: String!
county: String!
population: Int!
metrics: Metric!
riskLevels: RiskLevel!
actuals: Actual!
lastUpdatedDate: String
url: String
metricsTimeseries: [Metric!]
actualsTimeseries: [Actual!]
riskLevelsTimeseries: [RiskLevel!]
}
type State {
fips: String!
country: String!
state: String!
population: Int!
metrics: Metric!
riskLevels: RiskLevel!
actuals: Actual!
lastUpdatedDate: String
url: String
metricsTimeseries: [Metric!]
actualsTimeseries: [Actual!]
}
type Metric {
testPositivityRatio: Float
caseDensity: Float
contactTracerCapacityRatio: Float
infectionRate: Float
infectionRateCI90: Float
icuHeadroomRatio: Float
icuHeadroomDetails: ICUHeadroomDetails
icuCapacityRatio: Float
date: String
}
type ICUHeadroomDetails {
currentIcuCovid: Int
currentIcuCovidMethod: String
currentIcuNonCovid: Int
currentIcuNonCovidMethod: String
icuCapacityRatio: Float
}
type RiskLevel {
overall: Int
testPositivityRatio: Float
caseDensity: Float
contactTracerCapacityRatio: Float
infectionRate: Float
icuHeadroomRatio: Float
icuCapacityRatio: Float
date: String
}
type Actual {
cases: Int
deaths: Int
positiveTests: Int
negativeTests: Int
contactTracers: Float
hospitalBeds: HospitalBed
icuBeds: ICUBed
newCases: Int
date: String
}
type HospitalBed {
capacity: Int
currentUsageTotal: Int
currentUsageCovid: Int
typicalUsageRate: Float
}
type ICUBed {
capacity: Int
currentUsageTotal: Int
currentUsageCovid: Int
typicalUsageRate: Float
}
`
I went all out here on models. I left very few keys out and got a lot of great information here. Start small and incrementally add-in types if this is a lot. Or get it all done in one pass.
Update Resolvers to Resolve Correctly
As part of any of our query functions, there is a list of inputs provided to each query.
fieldName: (parent, args, context, info) => data
We don't need parent or info for our functions but what we do need is access to the input args or arguments and the context because that includes our dataSources nested inside our defined Apollo GraphQL server.
// resolvers.js
Query: {
counties: (_, __, { dataSources }) => dataSources.covidApi.getAllCounties(),
county: (_, { fips }, { dataSources }) => dataSources.covidApi.getCounty(fips),
states: (_, __, { dataSources }) => dataSources.covidApi.getAllStates(),
state: (_, { stateCode }, { dataSources }) => dataSources.covidApi.getState(stateCode),
},
Validate
Once you've wired up your newly created REST Data source to resolvers, you should be able to test in the playground.
Faking a Relationship Through API Calls
Let's say the consumers of this API are building a US map showcasing a state and it's counties impact from Covid-19. They want both a US state and all counties to render their UI. If this isn't already a REST endpoint, it is two endpoints: the /state/OH and the /counties endpoints. Let's combine these to push off the lifting to GraphQL and away from the client-side.
Add County Array to State
// schema.js
const typeDefs = gql`
type State {
counties: [County!]
fips: String!
country: String!
state: String!
population: Int!
metrics: Metric!
riskLevels: RiskLevel!
actuals: Actual!
lastUpdatedDate: String
url: String
metricsTimeseries: [Metric!]
actualsTimeseries: [Actual!]
}
Get Counties in getState
// CovidActNowAPi.js
async getState(stateCode) {
const state = await this.get(
`state/${stateCode}.timeseries.json?apiKey=${process.env.COVID_ACT_NOW}`
);
const counties = await this.get(`counties.json?apiKey=${process.env.COVID_ACT_NOW}`);
return {
...state,
counties: counties.filter(({ state: stateCode }) => stateCode === state.state),
};
}
If you want you could also add counties to the getAllStates function at this time. Although it won't perform well, it is better here rather than on the client-side.
Validate Counties in State
Test out to make sure you can query what you expect.
{
state(stateCode:"OH"){
state
counties{
fips
county
population
metrics{
testPositivityRatio
}
actuals{
cases
deaths
}
}
}
}
Up Next: Schema First vs. Code First
If you're interested in learning the pro's and con's behind these two GraphQL approaches, stay tuned for my next post where we will take the API written in this tutorial and take it a step further by switching from schema first to code first and scaling up with better developer tooling. I'm kind of winging it on where to go next. If you want to see something specific let me know.
Summary
We have created a GraphQL API from scratch, built a REST service data source to leverage our existing services, and got to utilize the playground to start to see some of those GraphQL perks. If you got lost at any point here is the repository code on the part1 branch. You also can reference the playground hosted on Heroku to try out some queries.
Top comments (0)