The output to the console should be something like this
This tutorial is, of course, not limited to this particular version. Due to rapid changes in the Node JS environment, it’s better to use the LTS version.
What libraries should we use?
First of all, we need to install the graphql-js library, which implements the GraphQL specification for Node JS and Express in our project. As for the integration of these two libraries, we basically have two options. We can use either express-graphql or graphql-server from the Apollo team. There are only minor differences between the two. Both libraries are middlewares for Express. However, graphql-server also has integrations for other frameworks like Koa or Hapi. If you are using the Apollo client, it’s better to use graphql-server-express. In this article, we will use the express-graphql library, as its GraphiQL implementation has default support for saving history of queries and mutations.
Edit 11.8.2017: Default GraphiQL history support has been also added to graphql-server-express
If you want to switch to a different library, the structure of the project should be similar and you will only have to replace the Express middleware. If you have already set up a project, this can be installed using yarn or npm
npm i express-graphql graphql --save
Starting your project
We will not go into project setup using yarn or npm as it is common knowledge and can be easily found elsewhere. The code snippets in this article use ES6/7 syntax, and therefore the babel-preset-stage-0, babel-preset-es2015, and babel-polyfill have to be installed. In addition, linting with airbnb rules should be set up. The final repository can be found at https://github.com/a7v8x/express-graphql-demo. Assuming you already have git installed on your computer, you can clone the repository with this command
git clone https://github.com/a7v8x/express-graphql-demo.git -b feature/1-setting-up-basic-graphql-server-in-nodejs-with-express
If we want to start right away we can just clone the repository, switch to the relevant branch and then go directly to GraphiQL section. It may also be helpful to look through the following section before moving on.
Designing our GraphQL schema
If you have already started a basic Express server using your own project code, you just need to add GraphQL middleware. In order to complete the server file code we can write the following
We will import graphqlHTTP and use it as the middleware for our /graphql endpoint. The Graphql endpoint is then available at the /graphql address and also GraphiQL is permitted in development mode because most of the time we do not want to expose our documentation in a production environment. The schema.js file can be written as follows
The UserType and UserInputType are defined as follows.
We have defined both queries and mutations, so we should include our definitions of user queries and mutations. This users.js file consists of the userQueries and userMutations object. These are then imported into the schema.
We have one query called users and one mutation called createUser. We can also see that every query or mutation consists of the following fields
- Query type definition (in our case the UserType definition)
- Arguments, which are passed most of the time as GraphQL variables
- A resolver, which is a function executed after calling and validating query or mutation
The structure of each query or mutation will be discussed more precisely in future articles. Because in the testing project we do not have a database, we used faker library for generating fake objects for our testing purposes.
GraphiQL testing enviroment
When we open the url http://localhost:3000/graphql, the browser page should look like this
This is our training ground. Personally, this is one of my favourite features of GraphQL. The development is so much more efficient and pleasant, than usinge some third-party tool like PostMan for creating a REST API. If we write down the queries, we can test our queries and mutations and also view the history of previously called requests like in this screenshot
GraphiQL is not only useful for testing our schema, but also for having up-to-date documentation. When we click on the Docs label, we can walk through the schema.
Testing your schema
Now it is time to test our created schema. This can be done with the GraphiQL browser IDE. We can define the GraphQL query string using the GraphQL specification. In this article, we just introduce the code snippets. We will go deeper into the structure of mutations or queries in the future. Our query is called users and we can execute the query by passing this code to GraphiQL. Our query is called users and we can execute the query by passing this code to GraphiQL
After hitting Play button, we should be able to retrieve data generated by faker
Now we have tested all queries in the schema and we can proceed to mutation testing. We only have one mutation which can be executed like this mutation for creating user
We should be able to retrieve this response