Getting started with GraphQL on Heroku
Tags: graphql, heroku, beginners, help
Published: 2019-05-07 17:05:14

---
title: Getting started with GraphQL on Heroku
published: true
description: a beginner's guide
tags: graphql, heroku, beginners, help
---


## Understanding the Purpose, and some key early tips

What is GraphQL? The answer to all of life’s problems? Maaaaaaybe? But it isn’t a database or a web server, the two things its most often confused for. Let’s dive in.

GraphQL is a communication standard.  Its goal is to let you request all the data you need with a single fairly compact request. It was born as an attempt to improve on REST APIs for populating web pages with data. The classic conundrum looks like this:

WEBPAGE: When Bob comments on a photo, I want to show a tooltip with profile pics of Alice and Bob’s top 5 mutual friends.

APP: okay, here’s Bob’s ‘user’ record

WEBPAGE: this has all his friend’s IDs, I need their mutual friends.

APP: hey good news I built an endpoint that takes two users IDs and returns their mutual friends

WEBPAGE: Great!

APP: they have 137 mutual friends

WEBPAGE: geez I want the top 5 by date, but… okay, now can I get their profile pictures

APP: sure here’s the first friend’s ‘user’ record

WEBPAGE: I need-

APP: here’s the second friend complete ‘user’ record

WEBPAGE: you don’t just have the photos?

APP: nope! Here’s the third friend’s ‘user’ record. Geez this is taking a while, huh? SOMEone’s on 3g, amirite?

-fin-

What’s wrong with this picture? In general two things:



*   Overfetching: while most REST API’s will have a way to ask for a ‘top 5’, there’s usually no way to ask for *some* information. We only wanted Bob’s mutual friends, and then after that we only wanted the mutuals photos not their full profiles
*   Multiple round trips: the very last request, for all 5 mutual friends` user profiles could be done in parallel, but all the steps before that would have to happen synchronously, waiting for a full reply before the next step could happen. If you think this isn’t a problem, you need to be a bit better informed about [the public’s level of broadband access](https://www.brookings.edu/wp-content/uploads/2016/07/Broadband-Tomer-Kane-12315.pdf)

In this scenario, no ‘bad engineering’ happened with this REST API, in fact the work’s been done to return filtered and scoped lists for some requests! But it is true that the front-end page team doesn’t have access to set up the exact API endpoints they need. This is an important point and I want to emphasize it a bit.

**If you have full access to alter your REST API, you don’t need GraphQL**

If your pal, the backend developer, is working with you to set up this feature, they can absolutely set up user/views/top5mutualpics and give you just the data you need, but the trouble starts as your operation grows and features on the front end need to be delivered without API changes. This probably means your org is growing, your user base is growing, and that you expect the frontend to grow and change without updates to your API, so it’s probably a good thing! 

GraphQL allows you to request data to the depth and in the shape that you need. It also implicitly lets you scope your request to get only the fields you need


```
{

  hero {
    name
  }
}

```


The response we get back will be in this shape:

```
{
  "data": {
    "hero": {
      "name": "R2-D2"
    }
  }
}
```


_This example is done on the lovely Star Wars API (SWAPI) endpoint, check out its [GraphQL interface here](https://graphql.org/swapi-graphql/?query=%7B%0A%20%20allFilms%7B%0A%20%20%20%20edges%7B%0A%20%20%20%20%20%20node%7B%0A%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A%0A%23%20%7B%0A%23%20%20%20allFilms%7B%0A%23%20%20%20%20%20edges%7B%0A%23%20%20%20%20%20%20%20node%7B%0A%23%20%20%20%20%20%20%20%20%20title%0A%23%20%20%20%20%20%20%20%20%20releaseDate%0A%23%20%20%20%20%20%20%20%20%20characterConnection%7B%0A%23%20%20%20%20%20%20%20%20%20%20%20characters%7B%0A%23%20%20%20%20%20%20%20%20%20%20%20%20%20name%0A%23%20%20%20%20%20%20%20%20%20%20%20%20%20gender%0A%23%20%20%20%20%20%20%20%20%20%20%20%7D%0A%23%20%20%20%20%20%20%20%20%20%7D%0A%23%20%20%20%20%20%20%20%7D%0A%23%20%20%20%20%20%7D%0A%23%20%20%20%7D%0A%23%20%7D)!_

So there’s no need to create separate /profile /profile_posts and /profile_vitals endpoints to get more focused versions of the data


# Pro-tips for the beginner

I saw an amazing talk from [Sean Grove](https://twitter.com/sgrove) of One Graph who works on maintaining GraphiQL, the rad graphical explorer for GraphQL. He talked about adding automations to GraphQL to let it point new query writers in the direction of more efficient coding of GraphQL queries. The query language is supposed to be easy, so these points shouldn’t add significantly to the weight of writing new queries.


## Optimize with variables

Let’s look at a basic query to load the hero of a Star Wars episode, and the names of their friends:

```
hero(“NEW HOPE”) {

    name

    friends {

      name

    }

  }
```

This looks pretty good but _updating_ this query will require some string manipulation by our GraphQL client. Also, later queries with different parameters will not benefit from any caching, since the GraphQL server will see it as a whole new query. So it’s better to add a variable to a query, then re-use the same query over and over:

```
query HeroNameAndFriends($episode: Episode) {

  hero(episode: $episode) {

    name

    friends {

      name

    }

  }

}
```

_This example and others in this article are cribbed from the [GraphQL learn pages](https://graphql.org/learn/queries/)_

Now we can update the episode variable and re-run the same query, and it’ll impact the client less AND return faster.


## Set defaults for your variables

If you love the other devs on yourself or even future you, you’ll set defaults on your variables to make sure each query succeeds


```
query HeroNameAndFriends($episode: Episode = JEDI) {
  hero(episode: $episode) {
    name
    friends {
      name
    }
  }
}
```


Later you can re-use this query as 


```
HeroNameAndFriends('EMPIRE') 
```


and benefit from caching!


## Write more DRY (‘don’t repeat yourself’) queries with fragments

It’s an amazing feature that you get to specify exactly the fields that you want to get back from a GraphQL query, after a while this can get… kinda tedious:

```

hero(episode: $episode) {

    name

    height

    weight

    pets {

        name

        height

        weight

    }

    friends {

      name

      height

      weight

    }

  }
```

If this was a query we might be asking for photos, IDs, friends’ IDs, over and over again as the query has more clauses. Surely there’s a way to ask for:

    name

    height

    weight

All at once? Yup!

Define a fragment like so:


```
fragment criticalInfo on Character {

    name

    height

    weight

}
```

Now our query is _much_ more compact:

```

hero(episode: $episode) {

    ...criticalInfo

    pets {

      ...criticalInfo

    }

    friends {

      ...criticalInfo

    }

  }
```

# Ready to dive in and go further?

My next article will cover how to host your first GraphQL server on Heroku, and after that how to build your first service architecture.

Your next step if all this is interesting to you should be to get a full series on [GraphQL queries right from the GraphQL team](https://graphql.org/learn/queries/) on their [learn page](https://graphql.org/learn/).

If you want to really learn GraphQL, I cannot recommend highly enough [“Learning GraphQL” ](http://shop.oreilly.com/product/0636920137269.do)by [Alex Banks](http://www.oreilly.com/pub/au/6913) and [Eve Porcello](http://www.oreilly.com/pub/au/6914).