DEV Community: Danijel Vincijanović

GraphQL for beginners

Danijel Vincijanović — Fri, 14 Feb 2020 17:53:55 +0000

Whoo, already five years have passed since Facebook publicly released GraphQL in 2015. It's not anymore just a new shiny thing - GraphQL ecosystem greatly matured and you should take it into consideration when choosing between different API design approaches.

If you're new to GraphQL, this article will help you understand how the client-server communication works and what are key differences between GraphQL and, most commonly used, RESTful API.

I'll show you how to make a request from the client to the server and we'll examine what is happening in the process. So, let's get started!

Schema and data types

Imagine that you're an astronaut 👨‍🚀. You want to buy a spaceship so that you can travel the universe with your friends. As an astronaut, you know about spaceship properties so you can easily define a type for it:

type Spaceship {
   model: String!
   weight: Float
   speed: Int
   turboEnabled: Boolean   
}

For defining Spaceship object type we've used something called "GraphQL schema definition language" or shortly - GraphQL SDL.

All Spaceship fields are built-in scalar types. GraphQL has 5 built-in scalar types: Int, Float, String, Boolean and ID. We're not restricted to only scalar types, a field type can be another object type or enumeration.

Notice how we've used an exclamation mark after the type name - String!. By using an exclamation mark we're expecting from the server to return a non-null value for the field. In the case that server returns null value for that field, an execution error will be triggered.

Now that we know how to use GraphQL SDL, let's define an object type for a shop 🛒 where we can actually buy a spaceship:

type Shop {
   name: String!
   address: String!
   spaceships: [Spaceship]
}

Every shop has a wide range of spaceships to offer - therefore, we have a field type [Spaceship] which represents a list of spaceships. Before moving further, we need to define how we can query our data. For this purpose, we should use a special Query object type:

type Query {
   spaceships: [Spaceship]
   shop(name: String!): Shop
}

We can look at Query fields as routes in REST - they are an entry point of the API. By examining Query type we can find out which data we can get from the server. In this case, we can get a list of spaceships and/or we can get a shop by name.

Finally, our GraphQL schema looks like this:

type Spaceship {
   model: String!
   weight: Float
   speed: Int!
   turboEnabled: Boolean   
}

type Shop {
   name: String!
   address: String!
   spaceships: [Spaceship]
}

type Query {
   spaceships: [Spaceship]
   shop(name: String!): Shop
}

Defining a schema should not be a task for Backend developers only. Frontend developers should also take a part in it because, in the end, they will consume the data from the server and use the schema as a documentation.

Query construction

This is the part where a client comes into play. We have our schema defined so we can perform queries to fetch some data. Writing a query is simple - it's basically selecting fields that you need. Let's say that you want a list of spaceships, but you only need their model and speed, nothing else. You would write a query like this:

{
    spaceships {
        model
        speed
    }
}

After that, perform a request to the GraphQL server with the query attached as a query parameter for GET requests or in body for POST requests.

fetch('/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({query: "{ spaceships { model speed } }"})
})

If everything went well, you'll receive a response like this:

{
  "data": {
    "spaceships": [
      {
        "model": "Mercury Conqueror",
        "speed": 2000
      }, 
      ...
    ]
  }
}

Additionally, if you want to get a shop by name along with the list of spaceships, you don't have to perform another request with a different query. You can modify the previous query and add additional fields. This way, we can get everything we need in just one request.

Things in the REST API world are a little bit different, if you want to get:

a list of spaceships, you would probably have to do a GET request to the /spaceships route
a shop by name, you would have to do a GET request to the /shop/:shopName route

You may notice that we had to do more requests with REST to fetch everything we need. Not only that we did more requests but we also get data that we don't necessarily need, meaning that we are over-fetching because an endpoint returns a fixed data structure. With GraphQL, you don't have to worry about under-fetching or over-fetching because you ask only for what you need 💰.

Parse, validate and execute

We're on the server side now; handling requests in REST is straightforward - every route (endpoint) is associated with a function (controller). When server receives a request it executes the function and returns result to the client. In most cases, before reaching the controller, we'll have to parse, validate and sanitize data that we've received from the client.

On the other side, GraphQL takes the query from our request and parses it to the Abstract Syntax Tree (AST). After parsing, it will take our schema and validate received query against it. We don't have to worry if client didn't send required data, provided a string instead of a number or maybe queried non-existing fields. GraphQL takes care of it and punishes the client with an error if necessary. If everything's fine, we can proceed to the execution phase.

Execution phase

GraphQL needs to know how to resolve each field for a given query. As a reminder, our Query object type provides two possible queries: spaceships and shop(name: String!).

type Query {
   spaceships: [Spaceship]
   shop(name: String!): Shop
}

To teach GraphQL how to resolve each field we have to write a resolver function for every Query field. The resolver function likely accesses database or does whatever needed to get the data and return it back.

const resolvers = {
  Query: {
    spaceships(obj, args, context, info) {
      return db.findAllSpaceships()
    },
    shop(obj, args, context, info) {
      return db.findShopByName(args.name)
    }
  }
}

Note: GraphQL is language agnostic and it is supported by many different languages. We're using JavaScript here. You can check here for more details about resolver arguments.

We can write resolvers for Spaceship and Shop object fields too. For example, we can resolve the speed field and return a different value if turboEnabled is set to true:

const resolvers = {
  Query: {...},
  Spaceship: {
    speed(obj, args, context, info) {
      return obj.turboEnabled 
         ? obj.speed * 2 
         : obj.speed
    }
  }
}

By default, if we omit resolvers, GraphQL resolves a field by returning property of the same name. GraphQL traverses tree and resolves each node (field). Resolved values will produce a key-value map that mirrors the original query. This result is sent to the client which requested it.

GraphQL use cases

Great thing about GraphQL is that you can place it on top of already existing API, so you don't have to do everything from scratch.

A common use case for using GraphQL is when the client needs the data from multiple sources. With GraphQL you can aggregate the data and let the client consume it from a single point in a standardized way.

Another use case is when there are multiple different clients which are using different data. Most likely, those clients will have to do several requests just to fetch needed data and will be prone to over-fetching and under-fetching. With GraphQL you can let every client choose which data to fetch.

What's next?

We've only scratched the surface; if you want to explore further I encourage you to check following links:

Sidenote: if you're looking for a remote JS dev, feel free to ping me 🙂

Hands-on React projects for practice

Danijel Vincijanović — Mon, 23 Sep 2019 20:07:28 +0000

As a JavaScript developer I had a chance to mentor a few people and show them how JS works both on the server and client side. Some of them were beginners and some already quite skilled JavaScript developers. Despite their experience level, in one point of time everyone needed some practical tasks to brush up on skills so that they can be ready when a real project kicks in.

For that purpose, I've already published some of those tasks that you can pick up and practice. As a sidenote, we're using them as a part of the selection process for an internship or a job.

cobeisfresh / frontend-tasks

Frontend tasks

Must read

Useful resources

View on GitHub

If you have some tasks that you would like to share with others, please post them in the comment.

If you solve task, feel free to send me a link to the solution and I will do my best to give you a constructive feedback!

Is this a €1.000,00 worth Node script?

Danijel Vincijanović — Thu, 29 Aug 2019 09:09:51 +0000

So the story begins with one of my favourite Youtube channels. A few days ago, they've published a new video announcing that they will soon reach their 100k subscriber and on that occasion will give out a €1.000,00 voucher which the person can then spend on new equipment.
That's a lot of money! Especially if you're, like me, living in Croatia. We're talking about approximate 20% more than an average monthly salary here.

Plot

I must admit, after I heard the announcement I was immediately hooked. I paused the video and started thinking of ways to become that 100k subscriber and win the voucher. What I figured out next is that manually checking the number of subscribers and waiting for the right moment to hit the subscribe button won't bring me any luck. I needed a machine to do that work for me if I want to be faster than others.

After a short brainstorming session I came up with an easy solution and the only thing I needed was Youtube API and a little bit of Node. Solution is pretty straightforward: we had to know how many subscribers the channel has so when it reaches its 99.999 subscriber we would need to subscribe.

Challenges

If you're already thinking about implementation then you know that we'll need setInterval or setTimeout so we can repeatedly check the number of subscribers.

The only limitation we have here is YouTube Data API quota usage. We get default quota allocation of 10.000 units per day which means that each request will cost us some units.

In our case, if we want to get a number of channel subscribers we need to do a request to https://www.googleapis.com/youtube/v3/channels?part=statistics and that request will cost us 3 units. You can calculate your quota cost using Youtube Quota Calculator.

If we check the subscribers count every second we'll drain our quota by running our script for 55 minutes which is just not enough; we want our script to run longer so that we don't miss out on our chance. The only solution for this limitation is to use a different interval delay depending on the number of subscribers. That means that we'll perform requests more frequently as the number of subscribers approaches 100k. In the beginning we'll start with one request per hour and then we'll get all the way down to 300 milliseconds.

Solution

Check the solution in this repo below and try it out.

davinci2015 / youtube-subscriber

Youtube Subscriber

If you want to know why this repo was created read this story about €1.000,00 voucher.

Installation

Clone repository

$ git clone https://github.com/davinci2015/youtube-subscriber.git

cd into directory

$ cd youtube-subscriber

Install NPM dependencies

$ npm install

Configuration

Before running the script you should update variables inside of config.js file.

Update following variables:

channelId
client_secret
client_id

Run the server

After updating config variables you can run server and let him do the magic.

$ node main.js

View on GitHub

Twist

After I've finished with the implementation, I continued watching the video where they announce their bounty. In that moment I knew I f***** up. It was never about being the 100Kth subscriber, it was about visiting their social profiles and participating in the prize game where the winner will be randomly chosen.

So here I am, with a published script and without a €1.000,00 voucher. But let's look at the bright side - at least I've learned something new and maybe, in the future, this script helps someone actually win the voucher, who knows.
Until then, happy coding!