651.288.7000 info@intertech.com

Why & How to Start Using GraphQL for Your APIs

by | Aug 10, 2019

If you’ve been following along with trends in web development, then you’ve likely heard about GraphQL. In brief, it’s a new specification for how to build an API. It’s also a query language for this new type of API. Indeed, GraphQL totally rethinks the traditional REST architecture of APIs. As a result, GraphQL APIs can be more intuitive and efficient to use.

Since its original development at Facebook, GraphQL has seen consistent growth in interest. At the present time companies like Atlassian, Coursera, Facebook, Intuit, KLM, Meteor, NBC News, PayPal, Pinterest, Shopify, The New York Times, Twitter, Wayfair, and Yelp are all using the specification to power their services.

In this post, we’ll examine what GraphQL is, how it works, and why it has grown so rapidly in popularity.


Traditional REST APIs: Multiple Requests & Overfetching

Undoubtedly, any web developer knows what a REST API is. That knowledge is critical to do any work with web applications. Indeed, REST-ful APIs have taken over the internet, powering most of the websites we use every single day.

Whenever you make a request to a REST API, you send that request to a specific endpoint. If you want information about the books in a library, for instance, you might make the request to library.com/api/books

In REST architecture, various endpoints are hyperlinked, so if you want more information on a specific book, you’ll need to visit that book’s uniform resource identifier (URI). For example, library.com/api/books/1 would give you detailed information on the first book in the library’s catalog.

If you want information on the book’s author, then you’ll need to make a different API request under REST architecture. For instance, that request might go to library.com/api/authors/<author_id>

As you can see, we’re making multiple requests to the API to get a book’s title and its author. Moreover, the REST API is probably over-fetching information that we don’t need and won’t use.

GraphQL vs REST

Contrarily, a GraphQL API provides a query language where we can specify exactly what data we want. In fact, a GraphQL API only includes one global endpoint that you send queries to. In turn, that endpoint processes your query and returns the result.

Accordingly, our book example above becomes a single query to the library.com/graphql endpoint:

   book(id: “1”) {
       author {

Within the query is everything we want to know. When we get back the response, it only contains what we asked for in JSON format:

“data”: {
   “book”: {
       “title”: “The Hitchhiker's Guide to the Galaxy”,
       “author”: {
           “name”: “Douglas Adams”


A Specification, Not an Implementation

As you can see, GraphQL involves learning a query language. However, once you learn it, you can get back exactly the data you need with a single request.

It’s important to realize, though, that GraphQL is not an implementation. You can’t download and install GraphQL itself. Instead, it’s merely a language and syntax specification. In fact, it is stack agnostic. You can use it in conjunction with any programming language, database, web framework, or UI library.

Furthermore, there are already great projects that are competing to provide GraphQL implementations in all languages and frameworks. This is a good thing because some of these implementations are easier to use or set up than others. Moreover, there may be specific features or support that your application needs that make one implementation make more sense than another.

The reference implementation of GraphQL is written in JavaScript on both the server and client-side. However, there’s nothing stopping you from using it inside any application, regardless of language.


Client-side Requests

On the client-side of your application. GraphQL is quite simple to use. Specifically, just implement one of the GraphQL clients that allow you to submit queries to a GraphQL endpoint. Once you do, you can start writing GraphQL queries like the book example we saw above.

In essence, think of GraphQL queries as asking for specific fields on an object. Moreover, that object might be connected to other objects that you can query by traversing the graph of object relationships. Hence the name “Graph Query Language.”

Whenever you run a query in GraphQL, the response will always have the same shape as the query you submitted. You won’t receive back extra fields or data that are ordered differently.

Additionally, GraphQL supports the use of arguments, aliases, reusable query fragments, and variables inside the query. As a result, you can construct highly dynamic queries on the fly in your application.


Server-side Schema & Resolvers

On the server-side, GraphQL APIs are a little bit more cumbersome to create. Because GraphQL is a query language, you’ll need to define schema and types for the data you’ll return. This works much like defining schema in SQL.

For example, this schema defines an object type of Starship with various fields on that object.

type Starship {
 id: ID!
 name: String!
 length(unit: LengthUnit = METER): Float

Notice how length accepts an optional argument for unit. If left blank, it will default to METER.

Your GraphQL service also needs to have a Query object that points various queries to their proper object schema. Think of the Query object as the entry point to your API for any incoming query.

For example:

type Query {
 starship(id: ID!): Starship

This just lets the GraphQL service know what to do when somebody comes with a request for a “starship.”

From there, you’ll need to build GraphQL resolvers in the language of your choice to handle incoming requests, fetch data from the database, and return as JSON. Luckily, many GraphQL service implementations make this fairly painless.


Using GraphQL as Your API

Using GraphQL has the potential to greatly reduce the number of API requests your application makes. While it does require developers to learn a new specification and syntax, it can be worth it in terms of efficiency of the response the API returns. GraphQL is definitely worth checking out, as its popularity is continuing to grow. In many applications, it could replace REST architecture for the better.


About Intertech

Founded in 1991, Intertech delivers software development consulting and IT training to Fortune 500, Government and Leading Technology institutions. Learn more about us. Whether you are a developer interested in working for a company that invests in its employees or a company looking to partner with a team of technology leaders who provide solutions, mentor staff and add true business value, we’d like to meet you.