The GraphQL Data Query Language: A Resource Guide
GraphQL is rapidly emerging as a viable alternative for the creation and publication of APIs.
Created by Facebook in 2012 to power their mobile app (leading Meteor core developer Martijn Walraven to quip that almost everyone is using a GraphQL API without even knowing it), GraphQL was released as an open source project at the start of 2015.
GraphQL is an application query language that is programming language agnostic and is often mistaken as a database query language. In a GraphQL API, the server describes what data is available, and clients can query exactly what data they need. As it is not a database query language, it does not include any filtering, sorting, computation or joins — although GraphQL queries do support parameters, which make filtering and sorting easy to implement.
For this reason, GraphQL is being chosen by developers needing to expose data to mobile and other client applications where REST payloads have become cumbersome. In a REST API architecture, a simple query may require three or more calls for data, and then that data needs to be parsed on the client-side for the interface to display the information needed. In GraphQL, all the data is accessed by a single endpoint, making it possible to query for exactly the data that the client application wants.
In GraphQL, the whole data model is described in a schema and resolve functions are defined to explain where and how to get the data from databases.
GraphQL is well suited to the complex, nested data models that are common in social media (where users, comments, likes and groups may create a web of relationships), e-commerce (where data relationships are connected across product catalogs, sales, wish lists, recommendations, inventory and customer data), and publishing (where articles/videos, authors/artists and viewer comments have many- to-many relationships). Publishers and e-commerce sites like The Financial Timers, Shopify and Coursera are already using GraphQL.
More recently, online video sites like Vevo and Vimeo have advertised vacancies for GraphQL developers. While these use cases are mostly internal, one of the first open GraphQL APIs made available was done so by GitHub in September last year.
It is also possible for GraphQL to be introduced incrementally into an architecture, meaning it is less an either/or decision compared with REST and is instead seen as a complementary technology that solves particular pain points around accessing data while ensuring low latency and reducing query complexity. In GraphQL, the whole data model is described in a schema and resolve functions are defined to explain where and how to get the data from databases.
GraphQL may be a new approach to API design and deployment, but it is gaining rapid adoption. Tooling for the GraphQL ecosystem is growing each month. A look at GitHub repos that mention GraphQL in the title or description are growing at just under 350 new projects each month, with 3,023 projects listed on GitHub at the start of the year.
Vince Ning, co-founder of the GraphQL backend-as-as-service provider Scaphold, expects the GraphQL community to continue to grow in two ways throughout 2017: “There will be top-down growth, with the rise of more and more public GraphQL APIs supported by large companies like GitHub. That will surely move the needle, says Ning “And there will be Bottom-Up growth. The tooling and services around GraphQL have only just begun to materialize, and the community around the technology is sprouting.”
The GraphQL architecture and ecosystem are made up of the following components:
- Specifications, shared concepts and knowledge management supports.
- Authentication.
- Backend-as-a-service providers.
- Schema Design tools.
- Server-side libraries and tools.
- Client-side frameworks and tools.
A bit more about each component, along with associated resources, follows:
GraphQL is supported by open source GraphQL specifications as well as training, community forums, an active blogging community, Summit events, and sample app code (1). The GraphQL workflow exists within a larger global environment where data is stored in data stores, legacy systems and accessed from APIs, microservices and functions (A). An authentication and identity access management component may sit outside the GraphQL architecture which manages permissions (2). Within the GraphQL architecture, the design is defined in a schema (4) which sits on a backend server (3). This includes function resolvers which describe how data can be accessed by client-side applications. Dev Tools on the server side (5) include performance analytics, batched query tools, subscriptions and WebSocket support tools, database adaptors that map external data stores into the GraphQL schema and acceptance testing services. Client applications (6) are built that can test queries and parse results directly from external APIs alongside requests to the schema, IDEs and code editing plugins and Chrome DevTools.
1. Specifications, Shared Concepts, Knowledge Management Supports
GraphQL specifications have been published by Facebook. The client application framework from Facebook, Relay, also details specific concepts around how GraphQL should function. For example, pagination is not detailed in the specs, but some best practices are emerging.
Many developers are following the sort of concepts and approaches to pagination detailed in Relay, even if they aren’t using the Relay framework per se. As Sashko Stubailo from GraphQL tools provider, Apollo, explained, “There isn’t yet a catch-all solution for paginating through data in GraphQL. Just like with REST, there are several different ways to do it.”
Resources
- All Your Queries Answered: GraphQL State of the Market Report (Platformable): Overview of uptake of GraphQL APIs, challenges and advantages, and current use cases.
- And GraphQL for all? (API Handyman): A few things to think about before blindly dumping REST for GRaphQL.
- Awesome GraphQL: A curated list of GraohQL resources.
- Building better APIs with GraphQL (Matthew Mueller): A priced Udemy course offering a step-by-step guide to building a better and faster API with GraphQL.
- Cheat Sheet (Sogko): GraphQL Shorthand Notation Cheat Sheet.
- Community resources (GraphQL.org): A directory of ways to join GraohQL communities, including Slack channels, IRC, on Twitter and in Facebook groups.
- GraphQL (Facebook): Website for the GraphQL project including learning resources and best practice discussions.
- GraphQL Europe: European-based GraphQL conference to be held in May.
- GraphQLHub (Clay Allsop): Blogs about GraphQL.
- GraphQL Open APIs (APIs-guru): A list of official open GraphQL APIs.
- GraphQL resources (Devknoll): A directory of GraphQL resources.
- GraphQL Summit (Meteor): GraphQL developer conference.
- GraphQL vs. REST (Phil Sturgeon): Blog post going into detail about advantages and challenges of GraphQL.
- GraphQL Weekly: A weekly newsletter of the best news, articles, and projects about GraphQL.
- How to build a GraphQL server (Apollo): Connecting SQL, REST and MongoDB to GraphQL.
- Learn Apollo (Graphcool): A hands-on tutorial for Apollo GraphQL Client.
- Learn GraphQL (Kadira): Walkthrough of GraphQL concepts.
- OK GROW! (OK GROW!): GraphQL Development and Training.
- Learning GraphQL (Mugli): One developer’s attempt to learn GraphQL.
- Zero to GraphQL (Steve Luscher): Examples of GraphQL endpoints created using various languages/frameworks.
2. Authentication
Authentication and authorization are often being handled by businesses as a separate concern outside of the GraphQL architecture. Developers who are using GraphQL in production environments tend to use an OAuth process to authenticate the client first. OAuth grants API tokens on a user basis, and then when making a GraphQL query, GraphQL only shows those fields that are allowable to users at that permission role setting. OAuth is used to identify permission scopes. In some cases, access permissions to data are defined at the database level in dataset metadata and also described in the schema documentation, where resolvers return null for any fields where permission is not granted.
Johannes Schickling, from GraphQL backend as a service provider Graphcool says GraphQL “works really well to support identity access management and authentication, but doesn’t limit you in how you do it.” He gives the example of how in the Graphcool product, it is possible to create different kinds of access rules at the field level, defined in the schema.
Data platform Curio has also found authorization to be a bit “quirky” in GraphQL. “With a GraphQL and Node-JS implementation, it does pass down the context object to resolve functions, which after the initial authentication ow, allows us to pass down the user information, and that is where we do the authorization,” explained co-founder Steve Willard.
“At the higher Node.js level, you resolve the schema at every request, so that allows per request schemas. We can handle the authorization at that level. So mutations get added to the schema if the user has the right to do so. We have those two levels of authorization so you can’t do request forgery if you grab a user’s request. What is neat about the per request schema is that as we dynamically build a schema, it makes it more efficient for us and speeds up the request.”
Resources
- Accounts (JS accounts): Full stack authentication and accounts management for GraphQL and REST
3. Backend-as-a-service providers
Commercial products from Scaphold, Reindex and Graphcool are already available and are seeing regular uptake amongst developer communities, with SimilarWeb reporting that each site has about 20,000 visitors each month. Each service provides a regular stream of content and tutorials on GraphQL and has engaging Slack channels where problems and queries are responded to quickly.
Resources
- Graphcool (Graphcool): Production-ready GraphQL backend.
- Reindex (Reindex): Reindex is a GraphQL backend as a service for React and React Native apps.
- Scaphold (Scaphold): Hosted data platform for GraphQL API.
4. Schema Design Tools
Besides the backend-as-a-service providers having schema design tools baked into their products, there is a range of open source projects available as well. These include database, API, and functions adapter tools which describe existing databases, APIs, microservices and functions into a GraphQL schema.
Resources
- Apollo-codegen (Apollo): Generate API code or type annotations based on a GraphQL schema and query documents.
- Compose (Nodkz): Tool that constructs a GraphQL schema, composes and relates types, builds helper functions that modify GraphQL types.
- ElasticSearch-GraphQL (Nordsimon): Schema and query builder for Elastic Search.
- Gestalt (Charlie Schwabacher): Use the GraphQL schema language and a small set of directives to define an API with a PostgreSQL backend declaratively, really quickly, and with a tiny amount of code.
- Graph.QL (Matthew Mueller): Faster and simpler technique for creating and querying GraphQL schemas.
- Graphcool (Graphcool): Production-ready GraphQL backend.
- GraphpostgresQL (Solidsnack): GraphQL for Postgres.
- GraphQL Schema (DevKnoll): Create GraphQL schemas with a fluent/chainable interface.
- GraphQL-tools (Apollo): Enables use of the GraphQL schema language to build a GraphQL.js schema including useful schema tools like per-type mocking.
- GraphQLviz (Sheerun): GraphQL Server schema visualizer.
- JSON to GraphQL (Aweary): Create GraphQL schema from JSON files and APIs.
- PostGraphQL (Caleb Meredith): With PostGraphQL, you can access the power of PostgreSQL through a well designed GraphQL server. PostGraphQL uses PostgreSQL reflection APIs to automatically detect primary keys, relationships, types, comments, and more providing a GraphQL server that is highly intelligent about your data.
- Scaphold (Scaphold.io): Define data model with schema designer and instantly get a GraphQL API backed by a highly available SQL cluster
- SQL-to-GraphQL (Rexxars): Generate a GraphQL API based on your SQL database structure.
- Swapi (Facebook): Example project that exposes existing SWAPI as a GraphQL server.
5. Server-side Tools and Libraries
Libraries exist for using GraphQL in all the major programming languages. Tooling is also being regularly created to provide additional options for query batching, subscriptions (equivalent to REST webhooks), performance monitoring and integration tools.
Libraries
C# / .NET
- Graphql-dotnet (Joe McBride & Jeff Moser)
- Graphql-net (Chad Kimes)
Clojure
- Graphql-cj (Lei Wang)
Elixir
- Absinthe (Absinthe)
- GraphQL (Asonge)
- Graphql-elixir (Josh Price)
- Plug-GraphQL
Go
- Graphql-go (Chris Ramon)
- Graphql-relay-go (Hafiz Ismail)
- Neelance/graphql-go (Richard Musiol)
Java
- Graphql-java (Andreas Marek)
- Spring Framework Boot Starters (Oembedler)
JavaScript
- Express-graphql (GraphQL.org)
- GraphQL.js (GraphQL.org)
- GraphQL server (Apollo)
- JSONAPI-server (HolidayExtras)
- Koa-GraphQL (Chentsulin)
- NodeJS API Starter (Kriasoft)
PHP
- GraphQL (Youshido)
- Graphql-php (Webonyx)
- Graphql-relay-php (Ivo Meißner)
- Laravel GraphQL (Folkloreatelier)
Python
- Graphene (Syrus Akbary)
- GraphQL Core (GraphQL-Python)
Ruby
- Graphql-ruby (R Mosolgo)
Scala
- Sangria (GraphQL.org)
Database adapters
- Graffiti Mongoose (RisingStack): MongoDB adapter.
- GraphQL-sequelize (Mick Hansen): GraphQL & Relay for MySQL & Postgres via Sequelize.
- Ember GraphQL Adapter (AlphaSights): GraphQL adapter for Ember Data.
- GraphQL-WP (Tim Field): GraphQL endpoint for WordPress.
Subscriptions
- GraphQL subscriptions (Apollo): A small module that implements GraphQL subscriptions for Node.js.
- Subscriptions Transport WS (Apollo): A work-in-progress GraphQL web socket server and client to facilitate GraphQL subscriptions.
Query Batching
- DataLoader (Facebook): Consolidates any calls to load() in order to batch-load data based on the collection of calls.
- GraphQL-Batch (Shopify): A query batching executor for the GraphQL gem.
- Join Monster (Stem): A GraphQL-to-SQL query execution layer for batch data fetching.
Performance Monitoring
- Optics (Apollo): Optics helps you understand the behavior and performance of your GraphQL queries, including a graphical field-by-field breakdown of each query’s cost and how it’s assembled. You can use Optics to monitor overall API usage, track which GraphQL queries are hitting your server, identify performance hotspots, and detect trends or changes in API workload.
Acceptance Testing
- GraphQL-CATS (CATS): A set of compatibility acceptance tests for libraries that implement the GraphQL specification.
6. Client-side frameworks and tools
Client-side GraphQL frameworks are advancing rapidly. In particular, an iOS client built by Apollo has rapidly moved from early release to being production-ready. A work-in-progress is available for Android although it is awaiting more feedback and support from the community before being officially launched.
Frameworks
Android
- Apollo Android (Apollo)
Elm
- Elm-GraphQL (Jahewson)
Flask
- Flask-GraphQL (GraphQL-Python)
JavaScript
- Apollo Client (Apollo)
- Express-GraphQL (Facebook)
- GraphQL-JS (Facebook)
- Lokka (Kadira)
- React Starter Kit (Kriasoft)
- Relay (Facebook)
- GraphQL-Relay-JS (Facebook)
- Vue-Apollo (Akryum)
Relate
Haskell
Ruby
- GraphQL Client (GitHub)
Serverless
- Serverless Starter Kit (Serverless)
Swift/iOS
- Apollo iOS (Apollo)
- GraphQL (GraphQLSwift)
IDEs and Dev Tools
- Apollo Client Chrome DevTools (Apollo)
- GraphiQL IDE (GraphQL.org): A graphical interactive in-browser GraphQL IDE.
- GraphQL IDE (Redound): An extensive IDE for exploring GraphQL APIs.
- GraphQL network (Ghirro): Chrome DevTool that provides a “network”-style tab for GraphQL requests to allow developers to debug more easily.
Coding plugin editors
- Language Babel (Gandm): Support for GraphQL code highlighting in the ATOM editor.
Query parsers
- ESLint Plugin (Apollo): An ESLint plugin that checks tagged query strings inside JavaScript or queries inside .graphql files against a GraphQL schema.
- GraphQL anywhere (Apollo): Run a GraphQL query anywhere, against any data, with no schema.
- GraphQL tag (Apollo): A JavaScript template literal tag that parses GraphQL queries.
- LibGraphQLParser (GraphQL.org): A GraphQL query parser in C++ with C and C++ APIs.
- Modelizr (Julien Vincent): Generate GraphQL queries from models that can be mocked and normalized.
Headless CMS
- Auto-generating CMS (Sarkistlt): GraphQL CMS will build a fully-functional CMS by just using your printed GraphQL schema without any changes in your existed code or architecture.
- GraphCMS (Lethal Webapps): A GraphQL-based headless content management system.
The above directory was created as part of the background research for the free GraphQL State of the Market 2017 Report: All Your Queries Answered, produced by Platformable and sponsored by GitHub and APIdays.
