Understanding, building, and using GraphQL APIs

One of my favorite sayings when it comes to API technologies is that the more things change, the more they stay the same. Networkable API technology has arguably been around since the early 1980s when the first remote procedure call (RPC) was implemented across a network. The basic features that characterize today’s networkable APIs — the network, the distribution of computing between nodes connected to that network, and a mutually agreed upon technical contract that codified how one machine can recognize the request from another machine — were also characteristic of those first RPCs.

Many of the core fundamentals of networkable APIs have remained unchanged over the last 40 years. Something else that hasn’t changed in the last 40 years is the quest to improve on the status quo. I began reporting on networkable APIs back in 1992 when MAPI for Microsoft Mail (the predecessor to Exchange Server), VIM for Lotus Notes, and MHS (Message Handling Service) for Novell Netware were competing for messaging API supremacy. Ever since then, we’ve been on a treadmill of API architectural styles. Each new style promises to be the end-all be-all (“let’s wash our hands, we’ve finally achieved API utopia”) and then, low and behold, another one comes along that once again moves the ball forward.

Following the still very fashionable REST architectural style for APIs, the latest two up-and-comers getting some traction — gRPC from Google and GraphQL from Facebook — even have a little “back-to-the-future” in them. Whereas REST took decoupling a step further by eliminating the remote invocation hallmark of its closest predecessor (XML-RPC and derivatives therefore), both gRPC and GraphQL arguably bring the RPC back. Whereas REST relies on the commands (verbs) of the independent protocol that connects the client to the server, GraphQL essentially requires the developer to deliberately invoke a server-side procedure by a previously known name. Whether that amounts to a resurrection of tighter coupling is a debate we’ll leave for another day. But maybe now, you know what I mean when I say the more things change, the more they’re staying the same.

New API architectural styles primarily influence our thinking at ProgrammableWeb in two ways. First, we take a close look at the technical specifics to see if the new style should, in some way, inform the data model behind our directory. For example, whereas streaming APIs (aka “evented APIs”) were traditionally treated as a separate architectural style of API, streaming is literally an option of both gRPC (tied to HTTP/2’s bidirectional streaming capability) and GraphQL (GraphQL Subscriptions).

This important advancement (or shift, depending on your point of view) is one of many evolutionary steps taken by the API economy that sent the ProgrammableWeb data model back to the drawing board for an update that is soon to go into production. Moving forward, an API listing in the ProgrammableWeb directory will now have the option of having both a primary and secondary architectural style. For example, as it turns out, Webhook-based APIs (another type of streaming/evented API) are pretty RESTful too.

For a new API technology to shape our thinking, two things have to happen. First, we need to see some real traction in the API economy. In other words, multiple API providers putting that technology into production for either internal or external consumption. Second, among ourselves, we need to develop a deep technical understanding of that technology and its unique value proposition.

Facebook may have invented GraphQL and put it into production for internal consumption in 2015. But it wasn’t until February 2017 that the first publicly available GraphQL — the Soundtrack API — was listed in ProgrammableWeb’s directory. From there, a few GraphQL APIs trickled-in throughout 2017. But then, the number of GraphQL APIs in ProgrammableWeb's directory grew eight-fold with the majority of those being added in the first half of 2019. Between that and companies like Atlassian, Credit Karma, GitHub, Intuit, KLM, Pinterest, Shopify, The New York Times, WordPress and Yelp making it a prominent part of their private and public API strategies, we decided it was not only time to finally take a closer look, but to also offer ProgrammableWeb’s audience the Web’s most encyclopedic introduction, history, and hands-on tutorial on GraphQL.

The ProgrammableWeb team had two objectives when it came to offering this series. First, for it to be exhaustively comprehensive. Going back to the idea of how the more things change, the more they stay the same, we could very clearly see in the GraphQL specification how its inventors Lee Byron and Nick Schrock were informed and influenced by previous API architectures. We believe this history is extremely important to anyone regardless of whether GraphQL represents your first API experience, or if you've worked with previous API architectures. GraphQL is not necessarily for every API use case. Understanding the nuanced differences between the GraphQL and REST approaches to API provisioning will help you to make better decisions going forward.

The second objective -- always a factor in what we do here at ProgrammableWeb -- is to advance our tradecraft as online publishers of technical content. When we first launched API University, we also launched a publishing capability that's not found on most Web sites; the ability to easily navigate a multi-part series of Web content. Typically on the Web, navigation from one part to another of a multiple part series is done with text links that are hand-built into each part. But with API U's standard element for navigating the parts of a series, every part to every series gives you full access to all the other parts of those series.

But we didn't stop there. In this series on GraphQL, we have woven together the native capabilities of our publishing system with the capabilities of three other services. Any code we develop and publish for the purpose of educating our audience should be openly reusable and forkable. All of the code we published for this series is available as open source under the MIT Public License in a public repository on Github.com . The content found in that repo ties directly to a hands-on interactive learning experience that you will find over on Katacoda.com.

With Katacoda, you don't have to configure your own system to follow along. Just use the preconfigured virtual system we've provided to you in the Katacoda interactive learning environment. All of the steps to "hello world" and beyond discussed in our hands-on tutorial have been pre-programmed into that learning environment to making learning GraphQL as frictionless as possible. Lastly, we've offered the step-by-step as a series of videos that are not just viewable on ProgrammableWeb's YouTube channel , they too are embedded directly into the Katacoda interactive learning environment.

We hope you enjoy our comprehensive API University series on GraphQL and as always, please feel free to let us know what you think of our content and how we've presented it.

David Berlind
Editor in Chief, ProgrammableWeb