Most web API providers probably already know about GraphQL by now. It’s the API query modeling language making waves throughout the API industry, allowing developer users to interact with a web API in an arguably cleaner method. The industry is still divided, though. While some venture to say it will replace REST in its entirety, others question whether GraphQL is worth it.
Outside of Facebook, the founders of GraphQL, there are actually quite a few API providers actually implementing GraphQL in practice. Usage keeps popping up in new environments throughout many public APIs, often utilizing GraphiQL, the official open source visual console for interacting with API calls. These visual interactive aids are designed to help developer users query data and perform mutations.
So, to add a little validation of the technology, let’s check out some companies officially implementing it with their public API programs. We’ll list 10 APIs using GraphQL, and test out their GraphiQL consoles with mock use cases to sample the behavior.
GraphiQL: GraphQL API Explorer
GraphiQL is an open source IDE console for exploring a GraphQL server. It displays a code editor with autocomplete on the far left, comes with error highlighting, query results in the middle column, and a documentation explorer on the far right. You can demo the Star Wars API to test it out. The Query Variables on the bottom left show what is actually being manipulated in the request. For a developer consumer, a GraphiQL interface could be helpful for building GraphQL queries, viewing the types of data that are available, and more.
1: GraphQL Hub
First off, let’s consider the GraphQLHub aggregation. Created by Clay Allsopp, you can use it to explore 5 popular APIs: Hacker News, Reddit, GitHub, Twitter, and Giphy using GraphQL. Though it’s technically an unofficial proxy — not manufactured by these companies — it’s a unique demonstration of the power of GraphQL to combine disparate elements into the same query style.
Say I wanted machine readable data of my last 5 posts to Hacker News, with the URL, score, and unique identifier. Using the GraphQL Hub interface, we can easily query this and read the results in JSON.
Reminiscent of a Postman API collection, a GraphQL “hub” could be used by a team to easily interact with their own unique API dependencies.
Brandfolder is an asset management service. With their API, developers can programmatically upload or retrieve brand asset files like images or fonts. They use GraphQLify to provide a GraphQL server and schema to act as a middlemen between the Brandfolder backend and frontend, translating a JSON API to interact with React/Relay applications. To play around here you’ll need an account and authorization.
Buildkite specializes in helping companies with continuous deployments. They’ve been driving front end development through the
https://graphql.buildkite.com endpoint. Their GraphQL API has even leapfrogged the web UI, as you can use it to schedule builds. Also built on the official open source GraphiQL, their GraphQL console is accompanied by a thorough step-by-step walkthrough; a good thing to consider to help new developers. As Tim Lucas of Buildkite states:
“GraphQL was made to be human friendly and empower people to easily use, explore, integrate with APIs.”
The European Holocaust Research Infrastructure (EHRI) provides access to holocaust related data and archive materials held in institutions throughout Europe. In addition to offering a Search API to access the database, The EHRI portal provides an experimental GraphQL API. As EHRI describes, GraphQL is a “faster and more efficient option when the data required in known in advance.” This echoes issues that some have with GraphQL being only accessible by developers familiar with the API.
GDOM is a web parser open sourced on GitHub. Using the Graphene framework, GDOM uses GraphQL syntax to traverse and scrape content off web pages. Another Hacker News example, here we use GraphQL syntax to traverse the Y Combinator home page and return top stories:
When will this become a full release? Well, GitHub places their GraphQL on the long-term side of their Platform Roadmap.
7: HIV Drug Resistance Database
GraphQL may also be useful in the context of academic research. Stanford University is currently using GraphiQL to visually query their Sierra Web Service, which interacts with their curated database of HIV drug resistance data. Below is a GraphQL call to retrieve a genomic sequence from a virus with a specific mutation:
8: Helsinki Open Data
HSL is the public transportation authority in the Helsinki, Finland metropolitan region. They produce data on routes, train stations, and more, which is all publicly accessible as open data on the HSL Developer Community. Say we wanted to retrieve basic information on all transit stations in the Helsinki area; we can use a single GraphQL query to list stations and fields such as station name, specific location, and more:
MelodyCLI is a dependency manager for Go. It helps save time by caching Go repositories, using a GraphQL API to routinely expose metadata on dependencies. Below we’ve used the melodyRepo Playground GraphiQL interface to retrieve dependency information on a specific GitHub package:
Superchargers.io is a web app map that provides the locations of Tesla stores, powering stations, and other service centers. Wholly based on a GraphQL API, the site does a nice job of onboarding developers to understand how queries behave.
Does Increased Usage Validate GraphQL?
Now used within asset management, academic study, public transportation, and more, you can see that GraphQL is getting around. However, trends alone shouldn’t validate the adoption of technology. So, why are more and more groups appreciating GraphQL? Well, as we’ve discussed before, there are some potential benefits:
- Better query efficiency: You can query multiple API calls simultaneously.
- More elegant data retrieval: Combining calls can return a lot of data with a single request.
- Low adoption overhead: Since GraphQL is a wrapper that can be defined, you don’t have to replace a REST system.
As the team behind melodyCLI put it:
“We chose GraphQL to give us greater flexibility in how metadata is structured while giving clients more flexibility in how it’s queried”
GraphQL should not be viewed as the stand-alone end all solution for everyone — many APIs still need developer documentation and strong API versioning strategies. A pain point is a lack of onboarding material in the GraphiQL interface; for developers unfamiliar with API calls, knowing how to structure a query is difficult as you will have to dig into documentation for the correct ids, field names, Strings, etc.
Tips on Making GraphQL / GraphiQL Awesome
With that in mind, for API providers considering providing a GraphiQL style IDE, here are some tips for getting the most out of it:
- Introduce what GraphQL is: The technology is still new to many, and they would love your help in structuring their first queries.
- Have example GraphQL queries: Auto-fill the GraphiQL skeleton with sample queries to help users get started. The Superchargers.io FAQ, for example, links to 4 different sample queries that populate a GraphiQL console.
- Have supplementary tutorials or FAQs on the side that explain your GraphQL schema and fields.
- Brand it: Lastly, it doesn’t hurt to include your own skins. Include branding on top of the blank GraphiQL layout to make it your own.
- Facebook cites roughly 70 companies implementing GraphQL here
- “GraphQL — A Legit Reason to Use It,” Edge Coders
- APIs.guru’s ongoing Collection of GraphQL APIs
- To help you get started, see this comprehensive list of community GraphQL libraries and tools
- Bruno Pedro of Hitch hq provides the counter argument: 3 reasons not to use GraphQL
- Learn GraphQL: Step by step tutorial introduction to GraphQL