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
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!
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 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
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 on their learn page.
If you want to really learn GraphQL, I cannot recommend highly enough “Learning GraphQL” by Alex Banks and Eve Porcello.
Top comments (0)