GraphQL API - an API you can really talk to!

Ivo Katunarić — December 10, 2018

Even though Facebook open-sourced GraphQL parser a few years ago, setting up a server to utilize it is still a chore. This first of a three-part blog post helps you set up and query a simple GraphQL nodeJS server.

The pain of being obsolete

Facebook open-sourced GraphQL parser back in 2015 with intent to kill (presumably). A few years later (if you’re coming from the future, it’s 2018 now), REST is suffering really badly, but still not dying. With your help, we can put it out of its misery.

A fat client is the boss these days

Angular, Vue and React are built around the frontend knowing everything and server being just a glorified database with authentication. That makes a client actually in charge of the application flow. If a server is just a database, a client should just Query it in some kind of Language. Also, Graph. GraphQL flavored with NodeJS is something you can read about in our next sections!

What makes a person?

An id, email, password hash, first name, last name and full name (which is really just a combination of the first and last name). We knew that one. But now, let’s tell it to GraphQL. It wants to know everything about your strange world!

type User {
     id: ID!
     email: String!
     firstName: String!
     lastName: String!
     fullName: String!
   }

Exclamation mark means that a field is excited about being required! Also, we left out password and password hash out because there are some people behind the API who hate puppies.

Great, but where do you grab a person?

At http://localhost:3000/graphiql if you’re using the server setup from our next section. User and Mutation are not enough for this one. You need another type: Query. It’s important because it puts Q in GraqhQL.

type Query {
   """ Grabs all users """
     users: [User!]!

   """ Grabs a single user """
     user(id: ID!): User
   }

Two exclamation marks mean that users are really excited about being a required array of objects which are always User and never null.

So great, but where do you grab a project to grab a person

From CoreLine’s GitHub page:

git clone https://github.com/CoreLine-agency/blog-post-demo-01
cd blog-post-demo-01
npm install
npm start

Open your browser at http://localhost:3000/graphiql.

What can I query?

Try pasting this (GraphQL) query into the console:

query {
   users {
     id
     firstName
   }
 }

When you’re ready to play, try clicking the “Play” button to see the list of all users in the system. Id and firstName are the fields that we expect from our graphql server.

If you want to fetch a single person by person’s id, you can do something like this:

query {
     user(id: "1") {
       firstName
       lastName
       id
     }
   }

What can’t I query?

Matt Damon! Because he doesn’t exist. You can’t query what doesn’t exist. Queries are great for fetching data, but mutations are needed to create or alter data.

mutation {
     createUser(email: "matt.damon@celebrities.com", username: "matt_damon", password: "pass123", firstName: "Matt", lastName: "Damon") {
       id
       email
     }
   }

Because Matt is a User, you can request any of the fields that User supports (id and email in this case). If we were to repeat the query from previous section, we’d see Matt along with users that already existed.

What’s next?

You can use the graphiql (i stands for interactive) console to explore all the capabilities of the graphql server downloaded from here.

While you’re having fun with the interactive console and all the users in it, we’ll be busy writing our next blog post to go into details of implementing the server used here. 😊

What about pros and cons of using GraphQL?

Here!