GraphQL?

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

A GraphQL query is a string that is sent to a server to be interpreted and fulfilled, which then returns JSON back to the client.

Defines a data shape: The first thing you’ll notice is that GraphQL queries mirror their response. This makes it easy to predict the shape of the data returned from a query, as well as to write a query if you know the data your app needs. More important, this makes GraphQL really easy to learn and use. GraphQL is unapologetically driven by the data requirements of products and of the designers and developers who build them.

Hierarchical: Another important aspect of GraphQL is its hierarchical nature. GraphQL naturally follows relationships between objects, where a RESTful service may require multiple round-trips (resource-intensive on mobile networks) or a complex join statement in SQL. This data hierarchy pairs well with graph-structured data stores and ultimately with the hierarchical user interfaces it’s used within.

Strongly typed: Each level of a GraphQL query corresponds to a particular type, and each type describes a set of available fields. Similar to SQL, this allows GraphQL to provide descriptive error messages before executing a query.

Protocol, not storage: Each GraphQL field on the server is backed by any arbitrary function. GraphQL had to leverage all this existing work to be useful, and so does not dictate or provide any backing storage. Instead, GraphQL takes advantage of your existing code.

Introspective: A GraphQL server can be queried for the types it supports. This creates a powerful platform for tools and client software to build atop this information like code generation in statically typed languages, Relay, or IDEs like GraphiQL (pictured below). GraphiQL helps developers learn and explore an API quickly without grepping the codebase or wrangling with cURL.

Version free: The shape of the returned data is determined entirely by the client’s query, so servers become simpler and easy to generalize. When you’re adding new product features, additional fields can be added to the server, leaving existing clients unaffected. When you’re sunsetting older features, the corresponding server fields can be deprecated but continue to function. This gradual, backward-compatible process removes the need for an incrementing version number.

Structure

A GraphQL server will have the following elements:

A schema — defines: data types, mutations and queries.
Resolvers — maps fields in the schema to data.
Datasources — REST, SOAP or database connection (e.g Apollo provides a MongoDB datasource).

An example

Requirement: A client application requires data from several APIs

In this example:

The Client can use one (potentially low bandwidth) connection.
The Client can request the exact data set required.
The GraphQL server act as a Façade over disparate data sources and protocols.
Data from the Client can be sent back for slower analytics systems to process without impacting user experience.

Detail

If we dig a little deeper into this example we see one of the key benefits GraphQL offers.

On the left we see a query defined in the schema and fulfilled by the resolvers via the data sources.

On the right we see a similar query with one field omitted, this results in the data source it is accessing not being called.

This potentially reduces latency, as less calls are required if the data is “thinner”. It also reduces load on the backend systems.

Considerations

Security — GraphQL allows multiple systems to be accessed concurrently. This presents an enlarged attack surface (e.g. DoS attacks via complex queries).
Complexity — For simple cases requiring a small amount of data, introducing GraphQL may be over complex (e.g. retrieving a single data entity which never changes).
Familiarity/culture — For teams very comfortable with REST or SOAP, GraphQL presents a significant learning curve and may be perceived as having little benefit.
Maturity — GraphQL is maturing rapidly as a technology, but it has only recently been introduced to commodity enterprise organisations.