I'm working on a series of a posts about GraphQL in order to get more familiar with what it is and what it's capabilities are. I hope you find these useful too!
- Part 1: What is GraphQL and how does it differ from REST?
- Part 2: Using the GraphiQL IDE to access a GraphQL API
- Next ➡ Part 3: Using GraphQL for .NET to access a GraphQL API
Finding a new API can be like discovering a gateway to a vast amount of data, which might be otherwise inaccessible. A couple of my favorites have led to photos from the Mars Rover and 300 year old newspapers.
These APIs are often implemented using REST, the standard for making web resources accessible for over a decade. In fact, when you access a webpage, your browser performs a
GET for the page and each resource it needs (images, style sheets, etc).
There's a different way to access web resources, called GraphQL. The first time I heard about it was a few years ago in some article about Facebook, but I didn't pay much attention to it at the time. I didn't realize until recently that Facebook actually developed it - and a few years ago, open sourced it too.
What is GraphQL?
As much as we'd like to think there's one "best" way to do things, GraphQL is an alternative for REST, not a replacement. And while there's quite a few differences between them, the major difference is that GraphQL lets you build a query to get exactly (and only) the data you're interested in.
An API that implements the REST interface allows you to (for example) very easily
GET some data about an entity - and by default, you get the whole shebang. If you can limit what you get, or customize the returned dataset somewhat, it's only because the developers wrote code to explicitly support those limits and customizations. How that looks will differ with every API... if it exists at all.
Take the Ghost API as an example, which is built into the blog engine I use for this site. You can request data on individual posts, authors, etc, which is all standard fare. On top of that though, the devs provided a few query parameters to affect the returned data:
- include returns more data, like full author details for a post
- fields returns less data, by specifying which fields should be returned
- formats returns more data, by returning data in multiple formats
- filter returns less data, by filtering by certain attributes
pagereturn less data by implementing paging
orderdoesn't even filter data, but it affects paging results so it's tacked on
Each of those items had to be explicitly coded, and while the Ghost API offers more customization than a lot of other APIs I've seen, they can only offer so much. If I want to "filter" by an attribute they don't support, I have to request more data than I need and filter it out locally. If I want to "include" some other entity they didn't plan for, I have to make multiple requests and stitch things together client side.
The flexibility in GraphQL is that it allows (forces, really) a client to create their own query to get just the data they want, in just the way they want it. And it also provides certain tools to enable the server to provide that data and only that data. In otherwords, GraphQL out-of-the-box returns the smallest amount of data needed, whereas REST returns the largest.
I wrote this post to force myself to do a little digging into GraphQL. It might not be too helpful to anyone else yet, but I plan on writing a short series of posts that elaborate on everything here and present some examples. There seems to be a pretty rich toolset for GraphQL, including:
- Some sort of IDE in the browser to play around with GraphQL
- Server libraries in C#, Python, and more (what's a server library?)
- GraphQL clients for C# and Python (what do they mean by client??)
- Various other tools (what do these do?!?)
Not to mention there's an entire GraphQL spec to check out... 😵
Dear. God. Okay I'm done.
I'll leave you with a couple introductory videos. The first one, by Scott Tolinski, is a nice quick overview that's less than 15 minutes.
The second is an hour long tutorial by Eve Porcello. She created a great introduction using GitHub's API, but it requires a Lynda.com account. I'd suggest checking with your library to see if they provide free access - mine did.