Micro Focus is now part of OpenText. Learn more >

You are here

You are here

The practical guide to GraphQL: The future of APIs

Mitch Pronschinske Senior Editor and Content Manager, HashiCorp

Most developers have heard the hype surrounding GraphQL, the query language for APIs and a server-side runtime. Rarely has this much enthusiasm around a software development technology built so fast, and some developers think GraphQL is poised to replace REST APIs in many application architectures over the next few years.

After two years in the open-source community, GraphQL has proved it has staying power, with projects, products, and services growing up to form an ecosystem around it. Now is a good time to research this topic seriously, and the list below will help with that.

The resources below include several introductions and well-researched opinions about GraphQL—including some competing ones. The list also includes tutorials, blogs, and resource collections to help you avoid the noise when looking for the most useful GraphQL learning materials. 

Understanding GraphQL

So what’s this GraphQL thing I keep hearing about?

In this comprehensive introduction, Sacha Greif shares GraphQL's origin story, illustrates its components in practice, and provides a bundle of resources to get started with it. The post also includes FAQs, along with a list of GraphQL servers, clients, and other tools.

An example GraphQL query.

A GraphQL Primer: Why We Need A New Kind Of API

Eric Baer's two-part series gives more historical background on APIs, recounting how they've evolved over the last few decades from remote procedure calls (RPCs) to using REST and SOAP, to GraphQL. Part two introduces GraphQL and outlines use cases, while also pointing out its drawbacks. The series is unique because it builds the reasoning for GraphQL from both history and current development needs.

GraphQL vs REST comparison - Is This Solution from Facebook Worth Taking the Risk?

After recounting why Facebook needed to build GraphQL back in 2012, Adam Żaczek explores several shortcomings of REST regarding its flexibility, overfetching, and documentation. The article concludes by going over GraphQL's advantages.

Why is GraphQL so cool?

Changelog podcast guest Johannes Schickling shares his expertise on GraphQL, explaining what it is, when it makes sense to use it, and its applicability in serverless architectures. He also discusses how the GraphQL community has grown in recent years.

A Front End Developer’s Guide to GraphQL

This article, by Peggy Rayzis, shares GraphQL examples—illustrating how to add new data requirements without adding a new endpoint, reduce your state management boilerplate, and use GraphiQL and Apollo DevTools for debugging. She leaves the reader with an example GraphQL app in React, Angular, and Vue to start experimenting.

A few things to think about before blindly dumping REST for GraphQL

While I don't think many teams are "blindly" dumping REST for GraphQL, Arnaud Lauret shares some useful information on GraphQL in his article. After a brief introduction to what GraphQL can do, Lauret explains the differences in developer experience between REST and GraphQL, and he explores GraphQL's impact on consistency and predictability.

He warns that GraphQL won't solve your existing API design and documentation problems, and he also shares some criticisms of GraphQL's experience for API providers. He notes that GraphQL may have unexpected impacts on your infrastructure because today's consumers have a lot more power in what they can ask for, and GraphQL may force you to rethink your API analytics and pricing model.

"So with GraphQL you gain great flexibility when querying data but you lose a certain predictability and consistency inside an API and across APIs."
Arnaud Lauret

The guide to learn GraphQL I wish I found a few months ago

Kalin Chernev explores a few areas where he got tripped up learning GraphQL. He thinks it can be harder for people who aren't familiar with the React JavaScript library, especially if you follow the route that uses the JavaScript reference implementation of GraphQL, graphql.js. The article includes some great GraphQL introduction videos and might help you save some time as you make decisions about your GraphQL learning path.

Predicting the future of GraphQL

Is GraphQL the Next Frontier for Web APIs?

This post by Brandur Leach is more skeptical about crowning GraphQL as the REST successor. Leach points out that for five years, hypermedia was pushed very hard as an upgrade to how developers build APIs, but it never caught on. He discusses GraphQL's benefits but also its downsides related to developer experience.

Leach compares GraphQL's usability to SQL, which isn't a glowing recommendation, given how many developers use object-relational mapping to make dealing with SQL easier. RPC and bespoke clients are two other alternatives to REST APIs that could seriously compete against the status quo, Leach says. But he thinks it will be hard for any of the options to do that, since one of the biggest benefits of REST APIs is their near ubiquity.

Is GraphQL The Future?

Alan Johnson gives his answer to this question in the first paragraph:

"Mark my words: in 5 years, newly minted full-stack app developers won’t be debating RESTfulness anymore, because REST API design will be obsolete. "
Alan Johnson

But the reasons he loves GraphQL aren't what you might think. Johnson sees GraphQL as neither a query language nor a graph-oriented tool. Its power, he claims, comes from its ability to allow the developer to build any facilities for specifying and fulfilling queries on their own. It lets you model the resources and processes provided by a server as a domain-specific language.

After taking a look at the GraphQL anatomy, Johnson explains why he considers GraphQL a meta-scripting language, argues why it's better than REST APIs, and explains why the GraphQL schema is not a data model. He notes that this is a post for those with an intermediate familiarity with GraphQL—meaning you've at least set up a GraphQL server.

Why I believe GraphQL will come to replace REST

In this article, Martijn Walraven, an open-source developer at the GraphQL utility company Apollo, describes a few REST API pain points and how GraphQL addresses them. He explains why migrating to GraphQL won't break backward compatibility and how it will also support your data needs going forward.

GraphQL's potential

GraphiQL: GraphQL’s Killer App

GraphiQL is an in-browser integrated development environment (IDE) for exploring GraphQL. Clay Allsopp says you have to try it out if you're learning GraphQL or debugging a GraphQL service. Allsopp points out the flaws in current methods for REST API exploration, while also showing GraphiQLs strengths. He believes that this tool is one of the reasons why you should move your APIs to GraphQL. You can also download a web and desktop GraphQL playground, with some additional features on top of GraphiQL.

How GraphQL Solves the Problem of Sprawling Architecture for the Enterprise

Matt Engledowl suggests using GraphQL as an API gateway to mitigate a common enterprise problem: Sprawling architectures with too many services. He describes the features of GraphQL that make it appropriate for this task, but warns that this is only a first step toward the long-term goal of fixing your service documentation and design issues.

"What’s going on behind the gateway may still be a big, hairy mess, but now you can more easily and quickly start fixing those pieces without creating a mess for the client-side applications."
Matt Engledowl

Does GraphQL Reduce the Need for Documentation?

Chris Ward, a technical writer, explores the documentation implications of GraphQL by doing a few experiments in GraphiQL. He concludes that GraphQL doesn't eliminate the need for documentation, and that technical writers' jobs are safe. The article also links to some useful resources on the documentation experience in GraphQL.

"From a documentation perspective, GraphQL is in essence, an API spec, much like other API specs like Swagger or API Blueprint. Granted, it’s much more tightly coupled to code than these specs, but this (directly) benefits developers more than writers or readers."
Chris Ward

GraphQL: Practical tutorials

How to GraphQL

For anyone learning GraphQL, this might be the best first stop right after the GraphQL docs. The site contains comprehensive front-end and back-end tutorials for GraphQL, with a variety of language and framework ecosystems—and even more coming soon. The site already has tutorials for Ruby, Java, Node.js, Python, Elixir, and React+Apollo ecosystems.

GraphQL tutorial selection by language.

A complete React with GraphQL Tutorial

The Apollo Client or Relay libraries can do a lot of work for you when using GraphQL, but making things easy right away isn't always the best way to learn. Robin Wieruch's React+GraphQL tutorial shows you how to perform GraphQL queries and mutations with plain HTTP requests. It's a large, comprehensive tutorial that walks you through building a simplified issue-tracking client for GitHub that consumes GitHub’s GraphQL API.

How to Build a Realtime Chat App with React and GraphQL

After you have researched the basic concepts behind GraphQL, you can try building an app using it. Chris Nwamba has written a tutorial for building a chat app that assumes you know the basic concepts behind GraphQL and React. He shows you how to set up a React and GraphQL project, how to use the Apollo Client to interact with a GraphQL server from React, how to query and mutate entities, and how to build real-time messaging and subscriptions. After this, you can check out his tutorial for building authentication into a React and GraphQL app.

Running a scalable and reliable GraphQL endpoint with Serverless

Siddharth Gupta has been working on tools using serverless architectures to solve big data problems. He found that GraphQL helps meet a lot of his needs, and wrote three tutorials on building serverless applications that use GraphQL. The first tutorial has a short intro to GraphQL, then jumps into a walkthrough for building a mini-Twitter clone. The app has serverless GraphQL endpoints using DynamoDB, Amazon RDS, and the Twitter REST API.

Gupta's first article also includes a performance analysis of the app, and it concludes with some pointers on how to convince your team that GraphQL might be worth adopting. The two other tutorials build the same app—one tutorial for the front end and one for the back end—but this time they use AWS AppSync, a managed serverless GraphQL service.

GraphQL blogs

Apollo Dev Blog

The open-source developers working on the Apollo Client for GraphQL have an excellent blog filled with tutorials and trend pieces. Like many blogs that address GraphQL, they have their own REST vs. GraphQL article. They also have posts on GraphQL authorization, schemas, caching, monitoring, and more.

Graphcool Blog

The Graphcool framework, a self-hosted back-end-as-a-service for building serverless GraphQL back ends, also has its own blog maintained by its open-source developers. The articles include "Top 5 Reasons to Use GraphQL," along with tutorials on "How to Wrap a REST API with GraphQL," how to deploy a cluster using Prisma (a GraphQL server tool), and a three-part series on GraphQL server basics.

Pusher Blog

Pusher, an API services company, has some helpful GraphQL tutorials in its archives as well. It also has a "REST versus GraphQL" article, along with three tutorials on handling authentication in GraphQL and one on building APIs with GraphQL and the Laravel PHP framework.

GraphQL community and ecosystem

GraphQL Weekly

One of the best ways to keep up with the latest developments on a topic is to subscribe to a dedicated newsletter, and GraphQL now has its own. The newsletter has been running consistently for more than two years.

Awesome GraphQL on GitHub

For a bird's eye view of a topic's tooling and resource ecosystem, few sites deliver better than the "awesome" repos on GitHub. GraphQL's awesome repo includes links to community forums, libraries and tools, services, databases, examples, videos, and blogs. You should also check out John Resig's recently published book The GraphQL Guide.

Do your due diligence

Whether you found some deeper tutorials to continue your GraphQL exploration, or you were introduced to GraphQL's advantages for the first time, now's the time to do more research. Branch out from these resources and keep up with the community to get better at working with GraphQL, or make a decision about whether or not to adopt it for your APIs.

If you have any awesome GraphQL resources that weren't shared on this list, please share them in the comments!

Keep learning

Read more articles about: App Dev & TestingTesting