JoinDownload

Getting started with GraphQL

7 Min Read

Vyom Srivastava

First and foremost, the biggest question is what is Graph QL?

GraphQL was designed by Facebook and if you check out the definition of GraphQL on their website it’s going to say something like this:

GraphQL is a query language designed to build client applications by providing flexible and intuitive syntax for asking the data requirement by clients.

Yes! The definition is totally correct, but it is very difficult to understand for a general public like you and me. So, let me break this into a smaller and easier syntax so that you can understand it.

The main goal behind designing GraphQL was to make the query smaller and smarter. You know so far, we have been designing these queries and designing endpoints such as APIs pretty easily and the only problem with them is that they’re over fetching or under fetching the data. Sometimes the data is so less that you have to make another query or sometimes the data is so much that you don’t use all of the data, you just use selective points of the data.

Nothing much big of a worry but when you’re at a scale of Facebook where billions and millions of people are querying the data every second, then it can be a little bit expensive on the cost of server because a lot of query is being fetched and data is transferred.

If we take an example, let me just tell you we want to fetch certain information from our website. For example, let’s try to fetch the age, name, gender, height, and highest score of the top 5 players that played in 2005 world cup. Yes it can be done, we can fetch the queries but now assume that the data that you’ll be fetching, it’ll be surely an overfetch. You’ll be fetching a lot of information and then we’ll be knit picking the information that is actually being asked.

Most of our API looks something like this /player, /player:ID, /country etc. Often these endpoints which don’t have any IDs just give you all of the information for that end point and often these endpoint which do have an endpoint, gives you the information about only one of the resource, but again the information is completely full and whether you require those information or not it is being served to you.

So for the IDs, the whole information is dumped and when you don’t have ID, you get giant pile of data. The only advantage that we get when we mention the ID is, we’re asking for one particular resource that we’re looking for, but still a lot of information is dumped. I am not getting just the name, height, gender and the highest score of that player but getting a lot more information like last name, email etc.

Example of Overfetching:

{
"player_details": {
"height": "2.1",
"weight": "78",
"gender":"M"
"age": "28",
"nationality": "USA",
"city": "NYC",
"state": "NY",
"zipcode": "1001",
"highest_score": "98",
"first_name": "Iron",
"last_name": "Man",
"middle_name": ""
"email":"iron.man@firecamp.io"
}
}

Example of Underfetching:

{
"player_name": {
"first_name": "Iron",
"last_name": "Man",
"middle_name": ""
}
}

Now imagine, you’re fetching 100 IDs so you’ll be making 100 API request and 100 response will be served to you. And now you’re extracting 5 information out of that. That is very very costly even for Facebook. They eventually thought that yes, we can cut down our resource consumption if we act a little bit smarter. The solution came in the form of GraphQL.

In GraphQL you can make selective end points like you don’t have to dump end points, you can just pick up selective information from that end point using GraphQL. It can dig a little bit deeper into you API end point and can pick selective information.

Is GraphQL related to Graph database? No, it’s like Java and JavaScript. I know both have Graph in name but both of them are used for completely different purposes. Surely, you can use both of them together, but they’re not related at all. The word graph here in GraphQL simply means that our queries are now able to crawl into the Rest API and pick up the selective information so that’s why the GraphQL actually came up and QL you already know it is Query Language.

Basically, GraphQL is a very powerful query language which allows for a more flexible and efficient approach that REST API. In REST API you hit multiple end point to fetch the data but in GraphQL you hit one end point and then ask for the stuff you want.

Benefits of GraphQL

  1. No over-fetching
  2. No under-fetching
  3. Reduced API calls
  4. Cost saving, as it reduces the number of calls and only returns what the client asks for.
  5. Out of the box support for validation and data type checking
  6. Generated the API doc automatically and keeps it in sync with the updates
  7. Easy to debug errors
  8. API evolves without versioning.

Basic Terms in Graph QL

Directive:

Directives are used for features such as authentication, incremental data loading etc. It acts as a middleware between an endpoint and the request. It uses prefix @.

Field:

It is the data which you ask in the request and it becomes the field of the JSON response data.

{
test
}

Schema:

It is the center of GraphQL and defines the functionality and end points which are available to the users when they try to connect GraphQL.

var schema = buildSchema(`
type Query {
test: String
}
`);

Query:

Query is used to fetch or read data from the GraphQL.

query getSingleUser($userID: Int!) {
user(id: $userID) {
name
age
shark
}
}

Mutations:

Mutations are used to write the data from the client.

type Mutation {
updateUser(id: Int!, name: String!, age: String): Person
}

Fragments

Fragments lets you to create reusable queries. It allows you to create sets of fields which you can use in your queries whenever you need them.

fragment userFields on Person {
id
name
age
shark
}

Type System:

Type system characterizes the set of data, which is used for validation, querying, execution in a GraphQL API.

type Person {
id: Int
name: String
age: Int
shark: String
}

Now we have covered the basic terms in GraphQL. So I think this is the right time to start with GraphQL.

Prerequisites

  • Node.js installed and basic knowledge of Node.js and express server

Step – 1: Server setup

The first step is for server setup is to create a separate directory for your project. So, open your terminal and write:

mkdir graphql_test

Obviously, you can give any name you want to give to you project. I chose this because I already had a project name “graphql”.

Then, cd graphql_test

We have to now initialize a npm project:

npm init -y

Now once you’re inside the project and initialized the npm, we have to install several dependencies which I’ll explain you why we need them.

Now run this command:

npm i graphql express express-graphql -S

Here in the above command we’re installing three packages:

First: GraphQL package for Node.js, is basically JavaScript implementation of GraphQL. Second: Express package, we need an express server to handle all the incoming requests and pass it onto the correct end point. Third: Express-GraphQL package, now we’re using this package to reduce the complexity of directly connecting GraphQL with Express.

Once you’re done with the task, we’re now ready to get our hands dirty with coding. Now in your terminal type

touch graphql_server.js

This will create and open a JS file where you can write you JS code. Now copy the below code:

const graphqlHTTP = require("express-graphql").graphqlHTTP
const express = require("express")
const { buildSchema } = require("graphql")
// Here we’re initializing a GraphQL schema
var schema = buildSchema(`
type Query {
test: String
}
`)
// Root resolver
var root = {
test: () => "This is the first output",
}
// Here we’re creating express server and a GraphQL endpoint
var app = express()
app.use(
"/graphqltest",
graphqlHTTP({
schema: schema, // Must be provided
rootValue: root,
graphiql: true, // Enable GraphiQL when server endpoint is accessed in browser
})
)
app.listen(4000, () =>
console.log("The URL to test API is: localhost:4000/graphqltest")
)

Now save your file, open your browser and go to this URL: localhost:4000/graphqltest

Don’t worry about the code I’ll explain all the stuff once the server is up and running.

You’ll see a two column page. On the left side you can write the query and on the right side you’ll have the output.

graph-ql-ss-1

Paste the below code and hit play button:

query testing {
test
}

You should see the below output:

{
"data": {
"test": "This is the first output"
}
}

Congratulations! You’ve made the first basic API from GraphQL.

Code Explanation:

const graphqlHTTP = require("express-graphql").graphqlHTTP
const express = require("express")
const { buildSchema } = require("graphql")

Here we’re using require to include all the packages required to run the code. These are the ones which we installed after initializing the npm project.

var schema = buildSchema(`
type Query {
test: String
}
`);

Now after including all the packages we’re creating the schema. Here we’re defining the data type for the query input that is string.

var root = {
test: () => "This is the first output",
}

After defining the schema we’re now defining what to return when someone hits the API root. So even if you hit the base URL of the API without any query parameter, it’ll return the default output. Also, if you pass the query test, then also it’ll return the same data.

var app = express()
app.use(
"/graphqltest",
graphqlHTTP({
schema: schema, // Must be provided
rootValue: root,
graphiql: true, // Enable GraphiQL when server endpoint is accessed in browser
})
)
app.listen(4000, () =>
console.log("The URL to test API is: localhost:4000/graphqltest")
)

Once everything is done, we’re now telling express server about the port number to occupy. We have used port number 4000 here, you can use any other port also as long asl that port is not occupied by any other service.

We’re passing our schema, root value and enabling the browser GraphiQL. That is the only reason you’re able to open it on browser.

Step -2: Setting up Schema

In GraphQL, schema is like the base of the API. It defines what values to take and what not. It defines all the types, data types, manage all mutations and queries. It defines the API’s type system.

Let’s just start with a very easy example:

var schema = buildSchema(`
type Query {
user(id: Int!): Person
users(shark: String): [Person]
},
type Person {
id: Int
name: String
age: Int
shark: String
}
`)

Here we’re updating the schema with new type system. We’re defining ID as integer, name as string, age as integer and shark as string.

You might notice that the id as ! appended, it is because for any query to run the ID is always required.

Step -3: Setting up Resolvers:

Resolvers are basically responsible for mapping all the operations. It tells the query where to pick data from.

Add the below code before buildSchema in graphql_test.js:

var users = [
{
id: 1,
name: 'Bob The Builder',
age: '44',
shark: 'Great White Shark'
},
{
id: 2,
name: 'Kim Jon Un',
age:55,
shark: 'Whale Shark'
},
{
id: 3,
name: 'Spiderman',
age: '23',
shark: 'Hammerhead Shark'
},
{
id: 4,
name: 'Batman',
age: '23',
shark: 'Tiger Shark'
},
{
id: 5,
name: 'Iron Man',
age: '25',
shark: 'Hammerhead Shark'
}
];
// Return a single user (based on id)
var getUser = function(args) {
var userID = args.id;
return users.filter(user => user.id == userID)[0];
}
// Return a list of users (takes an optional shark parameter)
var retrieveUsers = function(args) {
if (args.shark) {
var shark = args.shark;
return users.filter(user => user.shark === shark);
} else {
return users;
}
}

In the above code we’re adding data for our schema. The resolver will pick the data from this dataset only.

Now open the GraphiQL in your browser and paste the below code in the left pane of the page:

query getSingleUser($userID: Int!) {
user(id: $userID) {
name
age
shark
}
}

At the bottom left, click on “Variables” button. This will allow you to pass your own custom variables. Paste the below code:

{
"userID": 3
}

It should return this:

{
"data": {
"user": {
"name": "Spiderman",
"age": 23,
"shark": "Hammerhead Shark"
}
}
}

graphql-example

Step -4: Setting up Mutations:

We'll use mutations to update the data in the existing array of users. Add the below function, which we'll use to update the array:

var updateUser = function ({ id, name, age }) {
users.map(user => {
if (user.id === id) {
user.name = name
user.age = age
return user
}
})
return users.filter(user => user.id === id)[0]
}

Now we have to define the schema for updating the user details:

type Mutation {
updateUser(id: Int!, name: String!, age: String): Person
}

In the above schema we're passing the fields which are required for updating the user details. As you can see ID and name are required fields.

Now add the resolver also:

updateUser: updateUser,

We're done with the coding part. Lets head to Graphiql as pass the below code:

mutation updateUser($id: Int!, $name: String!, $age: String) {
updateUser(id: $id, name: $name, age: $age) {
...userFields
}
}
fragment userFields on Person {
id
name
age
shark
}

We're using fragments to define what we need in the output, to verify the results.

In the variables section paste the below code:

{
"id": 1,
"name": "Goku",
"age": "89"
}

As you can see, I'am a big fan of DragonBallZ. Once you press the play button, it should return the below output:

{
"data": {
"updateUser": {
"id": 1,
"name": "Goku",
"age": 89,
"shark": "Great White Shark"
}
}
}

graph-ql-ss-4

Step -5: Setting up subscriptions:

Since you're now familiar with Mutation part, I think it's the right time to move to subscriptions. So, subscriptions are basically used for realtime updation, deletion, and addition of the data. They're mostly used for realtime application like Chat application. Lets just dive into the code again this time we have to update the code also apart from adding new code.

We'll need another library also to run the subscriptions, so paste the below code to install the library:

npm i graphql-yoga

Again, open the js file and include the library:

const pubsub = require('graphql-yoga').PubSub()

Add a new resolver:

Subscription: {
user: {
subscribe() {
return pubsub.asyncIterator('user');
}
}
}

Also we have to update our updateUser function. This is how it'll look like:

var updateUser = function ({ id, name, age }) {
users.map(user => {
if (user.id === id) {
user.name = name
user.age = age
pubsub.publish("user", {
user: {
mutation: "Updated",
data: user,
},
})
return user
}
})
return users.filter(user => user.id === id)[0]
}

Now let's head to the GraphiQL tab on browser and now you can see a spinning wheel with message: "Listening". You can run any of the above inputs and it'll return the what was updated and what was added.

So far we have covered Server setup, schema, resolvers, mutations, fragments and subscriptions. I hope you understood all the basics of GraphQL and I made it easier for you to make you first API call with GraphQL.

GraphQL is a very powerful tool, but we cannot say that it’ll replace the REST API completely. You can use GraphQL or Rest API, it completely depends on your preference. In this tutorial we have covered most of the basics of GraphQL with some complex examples and we’ll come up with some more tutorials on GraphQL.

CONTENT
Benefits of GraphQLBasic Terms in Graph QLPrerequisitesStep – 1: Server setupStep -2: Setting up SchemaStep -3: Setting up Resolvers:Step -4: Setting up Mutations:Step -5: Setting up subscriptions:

Popular Posts

Most Secure API Authentication Methods

Authentication is a process that checks or verifies the identity of a user who tries to access any network, system, or device. Some access control mechanisms usually verify the username and password to get the identity of the user.

Nishchit Dhanani

13 Min Read

Links

DownloadDocChange LogsCookiesTerms & ConditionsPrivacy PolicyContact Us

Apps & Integrations

HTTPGraphQLWebsocketSocketIO

Firecamp Newsletter