GraphQL is a query language for APIs that offers declarative data fetching. It enables clients to ask for the exact data they need from a web server and nothing more. Developed in 2012 by Facebook, GraphQL API is currently being used in-house by Facebook and other companies such as Yelp, Shopify and Github. A GraphQL spec released in 2015 and is now available in many environments and used by teams of all sizes. GraphQL is open-source and maintained by Facebook.
While REST APIs typically send requests to multiple endpoints, GraphQL API allows you to send just a single request to an endpoint to retrieve data needed for your application. GraphQL is great for slow mobile network connections because it needs just one round-trip to the server to get the data it needs. Using GraphQL, front-end engineers can construct a query based on the fields they need from the endpoint rather than over-fetching or under-fetching resources from a REST API.
Versioning APIs can be headache for development teams. With GraphQL you have no worries. GraphQL allows you to add new fields and types (this will be discussed later on) to your GraphQL API without affecting existing queries. Older and unused fields can be deprecated and hidden from API clients. By using a single evolving version, GraphQL APIs give your application constant access to newer API implementations and allows clean and easily maintainable code base.
Before starting, make sure you have preferrably Node v6 installed. Open your command-line utitlity or terminal and type the command below:
If you can’t find Node installed, go the URL: node.org and follow the instructions to install it.
Setting up GraphQL and Express
A simple way to create a GraphQL API server is to use Express, a popular web application framework for Node.js. To get Express up and running you’ll need to install it using npm:
express-graphql dependencies like this:
--save flag is to add it as a dependency in your application so that anyone that installs your application automatical installs the dependencies when
npm install is initiated.
The initial structure of the folder will look like this:
Basic GraphQL API Implementation
Let’s have a sneak peak into the power that GraphQL API wields. We are going to be using the
buildSchema object from
graphql to create a schema. Create a
example.js file in the root directory and add this code:
example.js contains a basic structure of graphql. This API is implemented using the GraphQL schema language.
Express is not needed to execute this file. In your CLI terminal execute
example.js using the node command:
This is just to show you a quick example of a GraphQL API. I would explain later in this tutorial GraphQL Schema and how it works.
A key feature using
graphiql is that it allows you to test your API in the browser, autocomplete and make suggestions for you based on the types and fields available in your defined schema.
Now lets query our schema for
There you go! You have queried your GraphQL API.
By now you should have an understanding of how GraphQL works a bit. Let’s get started with building an Express GraphQL server. In the root directory create a folder
src folder create a file and save it as
schema.js. Now open the file and add this code:
The code is self explanatory. If you don’t understand it, I bet you would as you go on in this tutorial. Create a
data folder inside
src folder and copy the content of
posts.json files available here.
Types in GraphQL
GraphQL has a
graphql/type module used in type definition. Types can be imported from the
graphql/type module or from the root
Basic Types include
Boolean. We would be adding an
Author Type to our
What this does is to create an object of a
Name is self descriptive.
Description is self descriptive.
Fields contain the attributes of the
Author Schema such as the author’s
twitterHandle which all have their types defined. For more explanation on types check graphql types.
Let’s create our PostType:
Add it to
schema.js This will create a PostType object to be used in the
Creating the Root Query
Root query is an entry point to your GraphQL API server. It is used to expose the resources available to clients of your application. We would be making two resources available: authors and posts.
Let’s add this to the
Here Root query is defined as
description are self descriptive. If you noticed, there is a new type declared:
new GraphQLList(). What
GraphQLList does is to create a type wrapper around other types that represents a list of those types.
Defining a Schema
Schema defines how you want the data in your application to be shaped and how you want the data to be related with each other. Schema defination affects the way data will be stored in your database(s). In schema defination you’ll also be defining what
subscriptions that will be made available to the front-end displaying the data.
Lets add this schema to our file:
query is assigned the
BlogQueryRootType object to be used as the root query of the API.
GraphQL API implementation using GraphQL schema language
We will be needing a package
underscore library that’s great!. Lodash was created from it with some modifications made to provide additional functionality and deal with some performance issues in the underscore library.
This will install the lodash package and save it as a dependency in your
Add the following code at the top in your schema.js:
The following line of code makes the lodash library functionalities usable in
Now let’s take a look into the schema.js file, this is how schema.js file should look. You can get it on github.
If you notice in
PostType, we have an additional attribute
resolve. The function of
resolve is perform operations that involve data manipulation or transformation with a value returned at the end of the operation.
Types and query has already been discussed above.
BlogAppSchema will be exported to the
server.js file using
module.exports and by exporting BlogAppSchema we make everything available to our
server.js file in the root directory and add this code:
We can test is at
localhost:3000. In the root directory, open CLI terminal and execute:
This is how the server will come up. This is
graphiql and its helps you query your API in the browser. To test the API type the following query:
The result should look like this:
I am so excited and proud to have completed this tutorial with you. This is how to create a GraphQL API server powered by Express and NodeJS. I hope the tutorial was interesting and you learn’t alot. Let me know if you have any questions or contributions. I would be glad to hear it! If you want to know more about GraphQL visit graphql.org. For GraphQL vs REST comparism, take a look at this blog post written by Adam Zaczek.
Originally published on scotch.io.