How to Execute a Simple GraphQL Query
GraphQL is a query language that allows for highly customizable queries against Application Programmer Interfaces (APIs). GraphQL is on the rise and is currently being used in production-level applications by PayPal, Netflix, Shopify, Github, and Airbnb.
This tutorial will explain how to execute a simple GraphQL query. The prerequisites for this tutorial are a basic understanding of Node.js, the Express.js Web framework for Node, and how HTTP requests work. GraphQL is a query language and will work with environments other than the Node/Express environment but this tutorial works with Node/Express.
Getting Started and Installing Dependencies
Npm init (this will create the new Node project and package.json)
The following dependencies will be used for this project.
- express
- graphql
- express-graphql
- axios
The only dev dependency will be nodemon.
First, build the scripts. In the package.json, You’ll need to write two scripts that restart the server every time a change is made. The scripts are as follows:
The last part of the initial setup is the file tree. I only need to add two files for this: server.js and schema.js.
Building the Express Server
I’m going to require three items for this server to run: express, express-graphql, and schema. In addition to that. I’m also going to create an app variable which is an instance of express(), define port as 3000 and set up app.listen functionality.
At this point, my server.js looks like this:
The graphqlHTTP module provides a simple way to create an Express server that runs a GraphQL API. This project will only have one route handler, app.use. When using graphQLHTTP, the app.use functionality is set to an endpoint followed by the graphqlHTTP variable. It will connect Express to graphQL and its associated functionality.
For more reading on this, check out the GraphQL docs and the link to the GitHub Read Me, which is also incredibly helpful is here.
For this exercise, it really was as simple as copying and pasting from the GitHub Read Me just make sure to match the schema name to the schema variable name at the top of the file. graphiql:true refers to the /graphql endpoint pointing to GraphQL’s query testing platform, GraphiQL (think of it like the Postman for GraphQL).
Server.js will now look like this.
Build the Schema
Schema and query type building is really just outlining what incoming fields are expected and the data types they are (string, array, boolean). The formatting, though specific to GraphQL, is similar to any other concept in coding. It’s not new, just different. This project is querying a third-party API, the Star Wars public API so the steps are listed below:
- Define the data expected from the API
- Build the query object
- Export the schema
I’m going to require in Axios. The next thing I’m going to start requiring is the GraphQL types. Here’s a guide to the GraphQL types.
I’m definitely using the GraphQLObjectType and GraphQLSchema so I can require them first. It will look like this for now:
I’m going to be working with the Star Wars public API. I’m going to query the people data. I can see in the people section that each data point has its type listed beside it. I’m going to query for name, birth_year, starships, and vehicles so I will need to import the GraphQLString and GraphQLList in addition to the GraphQLObjectType and GraphQLSchema.
Defining the Data Shape — the PeopleType Object
The first GraphQLObject is the PeopleType:
The people type object will outline what fields the user can query for from the API and what data types the query can expect to receive. The key-value pairs in this object are as follows:
|
1 2 3 4 5 |
name: ‘String’, fields: () =>({ data_point:{ type: type_expected } }) |
The PeopleType object will end up looking like this:
Defining the Root Query Object
This is also a GraphQLObjectType as all objects built in the schema is a GraphQLObject type but the structure inside is different. The inside structure will look like this:
|
1 2 3 4 5 6 7 8 9 10 |
name: ‘String’, fields: { query_name: { type: type of data expected from the query, resolve: ( ) => { function requesting queried data } } } |
By copying and pasting this sample code into the browser, it’s clear that the key “results” provides an array of all the people objects. So the data type to query for is an array of people objects so in the type, it’s going to be a new GraphQLList(PeopleType).
Inside the resolver function will be the Axios request for data. It will look just like any other Axios get request. The object will end up looking like this.
The last step here is to export the schema which is incredibly simple.
For reference, the full schema.js file will look like this.
Run the server command followed by npm start and point the browser to localhost:3000/graphql.
Working with GraphiQL
Starting a query is as simple as {}. Type in the p and it will pop up a menu that says “people”. Open curly brackets again and enter fields to query. Press play and view the data collected.
They can be queried together or individually.
For sample error troubleshooting, go back to the code file and change res.data.results to just res.data and run the query and check out what it says.
One of the attributes of GraphQL is that data is nested, and with more intensive queries, data can be deeply nested and it can take a while to find where that data is located. Some of the error handling has to do with just making sure everything lines up.
For more on executing GraphQL queries, please see the GraphQL Docs on execution.
