GraphQL

NodeJS GraphQL: Setting up GraphQL Server with Node and Express #2

In this post, we will set up a basic GraphQL server with Express and Apollo Server

Founder @ednsquare | Continiously Designing Testing Coding at ednsquare | Any query? shoot an email at ednsquare@gmail.com

Published · May 3 2020

Previous tutorial: Introduction to building GraphQL API with Node and Express #1

Starting boilerplate code for this chapter can be found Github

In this section, you will set up the project for your GraphQL server and implement your first GraphQL query. We will be doing the following in this tutorial:
Setting up a development environment
Setting up apollo/express Project
Defining the GraphQL Schema

  
In the end, we’ll talk about theory for a bit and learn about the GraphQL schema.
. . .
Creating the project
This tutorial teaches you how to build a GraphQL server from scratch, so the first thing you need to do is create the directory that’ll hold the files for your GraphQL server!

Open your terminal and run the following commands:
mkdir nodejs-graphql-swapi 
cd nodejs-graphql-swapi 
yarn init -y 

Note This tutorial uses Yarn to manage your project. If you prefer using npm, you can simply run the equivalent commands using npm.

This creates a new directory called nodejs-graphql-swapi  and initializes it with a package.json file. package.json is the configuration file for the Node app you’re building. It lists all dependencies and other configuration options (such as scripts) needed for the app.
. . .
Setting up GraphQL server
With the project directory in place, you can go ahead and create the entry point for your GraphQL server. This will be a file called index.js, located inside a directory called nodejs-graphql-swapi .

In your terminal, first go to nodejs-graphql-swapi  directory and then the run below command to create empty index.js file:
touch index.js

To start the app, you can now execute node  index.js inside the nodejs-graphql-swapi directory. At the moment, this won’t do anything because index.js is still empty ¯\_(ツ)_/¯

Let’s go and start building the GraphQL server! The first thing you need to is - surprise - add a dependency to the project.
 Run the following command in your terminal:
yarn add express 
yarn add apollo-server-express

apollo-server-express is a fully-featured GraphQL server. It is based on Express.js and a few other libraries to help you build production-ready GraphQL servers.

Here’s a list of its features:
GraphQL spec-compliant
Realtime functionality with GraphQL subscriptions
Out-of-the-box support for GraphQL Playground
Resolves custom directives in your GraphQL schema
Supports Enums
and more...

Perfect, it’s time to write some code 🙌
 Open main.go and type the following:
// nodejs-graphql-part-2/after/index.js

const express = require('express');
const { ApolloServer, gql } = require('apollo-server-express');

// #1 Construct a schema, using GraphQL schema language
const typeDefs = gql`
  type Query {
    hello: String
  }
`;

// #2 Provide resolver functions for your schema fields
const resolvers = {
 Query: {
 hello: () => 'Hello world!',
  },
};

// #3 create the server from schema and resolvers
const server = new ApolloServer({ typeDefs, resolvers });

const app = express();
server.applyMiddleware({ app });

app.listen({ port: 4000 }, () =>
 console.log(`🚀  Server ready at http://localhost:4000${server.graphqlPath}`)
);

Note: This code block is annotated with a file name. It indicates into which file you need to put the code that’s shown.

All right, let’s understand what’s going on here by walking through the numbered comments:
The typeDefs constant defines your GraphQL schema (more about this in a bit). Here, it defines a simple Query type with one field called info. This field has the type String!. The exclamation mark in the type definition means that this field can never be null.
The resolvers object is the actual implementation of the GraphQL schema. Notice how its structure is identical to the structure of the type definition inside typeDefs: Query.info.
Finally, the schema and resolvers are bundled and passed to the ApolloServer which is imported from apollo-server-express. This tells the server what API operations are accepted and how they should be resolved.

Go ahead and test your GraphQL server!
. . .
Testing the GraphQL server
In the root directory of your project, run the following command:=
node index.js

As indicated by the terminal output, the server is now running on http://localhost:4000. To test the API of your server, open a browser, and navigate to that URL.

What you’ll then see is a GraphQL Playground, a powerful “GraphQL IDE” that lets you explore the capabilities of your API in an interactive manner.

  
 
By clicking the DOCS-button on the right, you can open the API documentation. This documentation is auto-generated based on your schema definition and displays all API operations and data types of your schema.

  
 Let’s go and send your very first GraphQL query. Type the following into the editor pane on the left side:
query {     
hello
} 

Now send the query to the server by clicking the Play-button in the center (or use the keyboard shortcut CMD+ENTER for Mac and CTRL+ENTER on Windows and Linux).

  
 
Congratulations, you just implemented and successfully tested your first GraphQL query 🎉

Now, remember when we talked about the definition of the info: String! field and said the exclamation mark means this field could never be null. Well, since you’re implementing the resolver, you are in control of what the value for that field is, right? So, what happens if you return null instead of the actual informative string in the resolver implementation? Feel free to try that out!

In index.js, update the definition of resolvers as follows:
// nodejs-graphql-part-2/after/index.js#L12

const resolvers = {
  Query: {
    info: () => null,
  }
}

To test the results of this, you need to restart the server: First, stop it using CTRL+C on your keyboard, then restart it by running node index.js again.

Now, send the query from before again. This time, it returns an error: Error: Cannot return null for non-nullable field Query.info.

  
What happens here is that the underlying graphql-js reference implementation ensures that the return types of your resolvers adhere to the type definitions from your GraphQL schema. Put differently, it protects you from making stupid mistakes!

This is in fact one of the core benefits of GraphQL in general: It enforces that the API actually behaves in the way that is promised by the schema definition! This way, everyone who has access to the GraphQL schema can always be 100% sure about the API operations and data structures that are returned by the API.

Learn more about the Lists Types and Non-Null here
. . .
A word on the GraphQL schema
At the core of every GraphQL API, there is a GraphQL schema. So, let’s quickly talk about it.

Note: In this tutorial, we’ll only scratch the surface of this topic. If you want to go a bit more in-depth and learn more about the GraphQL schema as well as its role in a GraphQL API, be sure to check out this excellent article.

GraphQL schemas are usually written in the GraphQL Schema Definition Language (SDL). The SDL has a type system that allows defining data structures (just like other strongly typed programming languages such as Java, TypeScript, Swift, Go, …).
. . .

In the next tutorial, we will be extending our schema & will add more queries to GraphQL API.

Up next:   Writing the GraphQL Query and Resolvers #3

Final code for this chapter can be found Github