What is GraphQL

What is GraphQL

GraphQL is a query language for APIs developed by Facebook in 2012. In simple words, it’s used to load data from a server to a client (i.e. from an API to your application) much more efficiently than traditional services.

It’s fair to say that GraphQL is unlike anything you might have used before which is precisely why a large number of organizations have switched over to it for building APIs.

In this article, I’ll take a closer look at some of the major problems behind current REST APIs and how GraphQL solves them while improving productivity. I’ll also explain some of the key benefits developers can experience by using GraphQL and whether you should make the switch from REST to GraphQL.

Let’s get started.

What’s the problem behind current APIs

Let’s start with an example.

 

Say that you want to fetch data from a Facebook REST API. You’d say Hey Facebook, give me this information. What happens behind the scenes is that you have a specific endpoint or URL that you’re hitting. That endpoint or URL determines what data comes back. You can manipulate what comes back or the shape of the data by passing in options (parameters) with the URL. 

NOTE: With standard REST APIs, you fetch a URL that returns a JSON or JavaScript object full of data. This is how things worked for a while. Right before that we typically worked with XML and web-services using the SOAP standard.  Now API’s have typically been REST API’s for a long time.

There are two main problems with the current REST APIs:

  • Over fetching. When more data is delivered upon fetching than is required. In these cases, you’re unable to utilize all of it.
  • Under fetching. When the data you get back is not enough. Often times, the data is so little that you have to run another query.

The most common endpoints for a traditional REST API are /myClassName or /myClassName:ID. In most cases, the endpoints that don’t have an ID give you all of the information for that specific endpoint whereas those that have the ID give you information about one particular resource.

The point being that in both cases, you’ll probably have an over fetch scenario i.e. more information than you need. And for the endpoints that have an ID, you will have all of the fields associated with the specified ID and for that specific endpoint. Simply put, without an ID you will have a huge dump of information that can’t be effectively utilized.

Though it isn’t a problem initially when you have a small app that only contains a few classes and users, it quickly becomes an issue when you start to scale. The cost of servers starts to rack up as you run more and more queries and request a lot of data to be transferred.

 

What makes GraphQL new and excitingly different?

Here’s a quick metaphor to better illustrate the difference GraphQL makes:

If you go to a restaurant and ask for a plate of food, that’s a traditional REST API request. In this scenario, you will get your food, eat what you want off your plate, and leave whatever you don’t want.

However, if you go to a self-service restaurant or a buffet, that would be a GraphQL request. In this scenario, you can choose whichever things you’d like to eat and how much you’d like to eat. This way, no food goes to waste.

Now you might be wondering what makes GraphQL truly different.

The main motivation behind GraphQL is to make the query smarter. So, instead of an API where you hit a URL and accept whatever data comes back, GraphQL allows you to specify exactly what data you need. In this way, you can:

  • Request specific kinds of data.
  • Aggregate data from multiple sources.
  • Dig deeper into your API’s endpoint and pick up selective information from it.

Let’s step through some code that is on the official GraphQL website.

In the code below, we’ve defined the way our data should look. For the purpose of the example, we’ll assume that it’s a project with a name, tagline, and some contributors.

Describe your data

type Project {
  name: String
  tagline: String
  contributors: [User]
}

The next step is to ask for what you want. This is the actual query you will run instead of simply hitting an API and accepting whatever data comes back. What will happen now is that you’ll say Hey, give me the project with the name ‘GraphQL’ and return only the tagline.

Ask for what you want

{
  project(name: "GraphQL") {
    tagline
  }
}


When you run the query, only the data you asked for will be fetched. Following our example, you’ll get an object with the project and tagline rather than the entire object which also contained the name and contributor’s list.

Get predictable results

{
  "project": {
    "tagline": "A query language for APIs"
  }
}

How does that make the developer’s life easier?

Here are some of the main ways GraphQL makes the developer’s workflow easier:

Benefit #1: Easier for front-end teams

The obvious benefit is that you will need less code to get the same information on the front-end. In addition to this, it’ll be much easier to understand for front-end developers as they will be able to take a look at the object and understand what it will return. As a result, front-end and back-end teams will be able to work faster.

Also, one of the first things you’ll notice with GraphQL is that its queries mirror the response. This allows you to better predict the shape of the data that will be returned from a query. It also makes it easier for you to write a query if you already know what data your app needs. 

Benefit #2: Don’t have to worry about API versioning

It’s important to note that the shape of the data that’s returned is determined by the client’s query. Due to this, servers become simpler and easier to generalize. As a result, when you add new product features, you’ll be able to add additional fields to the server without affecting existing clients.

Similarly, when you’re sunsetting older features, the corresponding server fields can be deprecated but will continue to function. This gradual, backward-compatibility process eliminates the need for an incrementing version number.

Benefit #3: It’s dynamic

One of the major advantages GraphQL brings to the table is that your API is dynamic and you can define it in development time. For development teams, this means less friction between front-end and back-end teams and a boost in overall productivity.

 

Should I abandon the REST API now that GraphQL is here?

The short answer is no.

If you already have a running application that uses the REST API, you don’t need to worry about migrating over to GraphQL. I would, however, recommend that you use GraphQL for all future applications – especially if it’s built to be scalable.

Keep in mind that GraphQL and REST are two completely different things. While GraphQL is a language and technology, REST is an architecture pattern. In simple words, this means that the REST API is still rock solid and most certainly here to stay. GraphQL is simply another resource that makes REST APIs smarter.

Most applications won’t experience huge performance gains from migrating to GraphQL. Significant improvements in performance are apparent when you scale your app. It’s an elegant solution for teams who have been limited by traditional REST APIs.

How can I get started with GraphQL?

This makes it incredibly easy to get started with GraphQL and begin using it. GraphQL is unapologetically driven by the data requirements of products and of the designers and developers who built them.

First, you’ll need a server that can serve your API and a client that can fetch the endpoints from the server. You can make the server by yourself using, for example, NodeJS and Express together with GraphQL. However, if you’d rather not waste time dealing with servers, you can use the Back4App Serverless GraphQL API.

One that’s done, all you have to do is create an app and start using it. Be sure to check out this step-by-step tutorial for more information. For the client, you will have a variety of resources. If you want to try something new, I’d recommend Facebook’s Relay together with React.

 

 

Resources that can help you learn

When using the Back4app GraphQL API Console, you can rely on Autocomplete, which will help you understand what are the possible next steps of your GraphQL query or mutation:

screen-shot-2019-08-06-at-10-18-02

Also, you can see the results of the query or mutation in real-time, so you know exactly what you are retrieving:

screen-shot-2019-08-06-at-10-23-50

As that wasn’t helpful enough, you have fully specified schemas for all your classes which you can download and integrate to your projects:

screen-shot-2019-08-06-at-10-27-21

And also, documentation for both specific and generic methods that you can use for reference when developing:

screen-shot-2019-08-06-at-10-47-46

 

Wrapping Up

GraphQL is a new and exciting technology that enables developers to build high-performing, scalable APIs without bumping into the limitations of traditional REST APIs. Essentially, it provides an easy-to-understand description of the data in your API and allows clients to ask for exactly what they need – nothing more, nothing less.

Do you have any questions about GraphQL? We’re happy to help so let us know in the comments section below!


Comment ( 1 )

  1. ReplySwarup
    Wonderful article. So McDonald's is Rest whereas subway is GraphQl. :)

Leave a reply

Your email address will not be published.