A brief introduction into GraphQL

James Hamann
Oct 22, 2018 · 4 min read

I know I’m a bit late to the GraphQL party but having had sometime recently, I thought I’d play around with it on a new side project I’m working on. Initially I found myself a bit lost, but after reading through the sites docs and understanding it’s purpose and the problem it solves, it made so much sense.

What exactly is GraphQL?

Created in 2012 and open sourced by Facebook in 2015,

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data.

Essentially it’s a library that describes how we retrieve data from the server to the client. Some of the main features are:

  • A Schema to describe your data
  • Retrieve as many or as little resources as you require in a single request
  • Continually develop your API without versioning

Let’s explore these features in a little more depth.

Schema

A huge benefit I found from the outset was being able to define my data, it’s types and relationships in a single Schema document. GraphQL is strongly typed, which means everything in the query is checked before an operation is executed. This ensures the syntax, data types and query are all valid before execution.

#yourSchema.graphql

This is a basic example of a Schema document. There are five default scalar types that come out of the box, those are String, Float, Integer, Boolean and ID. As well as these default types, you’re able to create custom scalar types, for example if you had a Date or Time data type you could define a custom scalar to be used in your Schema. The ! denotes whether a field is required or not.

Having a Schema provides a useful reference of your data and ensures there’s no ambiguity.

Retrieve as many or as little resources as you require in a single request

This is one of the features which is incredibly useful. The example query below will retrieve a list of all the items.

query {
items {
id
name
description
}
};

However, say we’re on a list view, we might only want the name and description.

query {
items {
name
description
}
};

This allows us to query and retrieve only the data we require, making it easier, quicker and more efficient to work with. It also reduces over-fetching.

As well as this, we have the ability to fetch the comments relating to that item with a few extra lines in our query request.

query {
items {
id
name
comment {
id
content
photo
}
description
}
};

Now let’s imagine we’ve got a complex dashboard view where we need to fetch multiple attributes from multiple resources. No problem!

query {
items {
name
description
}
comments {
content
}
todos {
todo
description
}
};

This single request will fetch only the desired attributes we’ve specified, from the multiple resources listed. It negates the need to perform many http requests to receive all the data you require, unlike REST APIs

Continually develop your API without versioning

REST APIs require versioning when deprecating or introducing new fields, as the server dictates the response and therefore the client needs to be able to process that response. The key difference with GraphQL is that the query itself dictates the response, as highlighted above, therefore the client will be compatible regardless of what new fields are added or deprecated.

Pros

  • Rapid prototyping and product development
  • Reduces over and under fetching of resources
  • Allow your API to evolve continuously without versioning
  • Strongly Typed — GraphQL can ensure the syntax, data types and query are valid before execution

Cons

  • Caching can be tricky
  • For more complicated use cases, queries can become bloated, nested and complex
  • Typical Rate Limiting is a little different, as with one endpoint, and with every query being different, the operation can either be expensive or cheap.

Conclusion

GraphQL offers an alternative way to architect your client — server relationship, it helps decouple your API from it’s consumers and makes it easy to iterate over your product without the fear of introducing breaking changes.

In a future post I’ll be taking a look at setting up a Serverless GraphQL React app in AWS and demonstrating some more of GraphQL’s features and benefits.

As always, thanks for reading, hit 👏 if you like what you read and be sure to follow to keep up to date with future posts.

Data Driven Investor

from confusion to clarity, not insanity

James Hamann

Written by

Software Developer https://jameshamann.com

Data Driven Investor

from confusion to clarity, not insanity

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade