Introduction to GraphQL
By: Oliver Vaughan
Tags: Apollo Server, API, GraphQL

GraphQL is a specification for accessing data over the internet. It is designed to facilitate the following statements:

Data should fit the needs of the client

The design of an API or data store should not dictate how that data is consumed

It is implemented as a service, which acts as an intermediary between backend systems and the client making the query.

GraphQL is designed to solve performance and management problems which become apparent when clients require data aggregated from numerous sources. It solves these problems by providing a query-able façade over these systems. This allows clients access to data aggregated from numerous APIs and data sources. It also provides a schema describing how to access these resources, which can be evolved.

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).

Definiton

According to GitHub’s blog GraphQL is:

1. A specification. The spec determines the validity of the schema on the API server. The schema determines the validity of client calls. 2. Strongly typed. The schema defines an API’s type system and all object relationships. 3. Introspective. A client can query the schema for details about the schema. 4. Hierarchical. The shape of a GraphQL call mirrors the shape of the JSON data it returns. Nested fields let you query for and receive only the data you specify in a single round trip. 5. An application layer. GraphQL is not a storage model or a database query language. The graph refers to graph structures defined in the schema, where nodes define objects and edges define relationships between objects. The API traverses and returns application data based on the schema definitions, independent of how the data is stored.

History

In 2012 Facebook were just about to declare an IPO. In the run up to this offering they performed a technical overhaul and decided that one of the biggest risks was the performance of their mobile applications. GraphQL was designed as a method of efficiently serving these mobile payloads.

As Facebook make money from advertising, they require slick systems of engagement (i.e. lightweight mobile apps), but need heavy backend storage and analytics systems to crunch and store usage data.

GraphQL was designed to facilitate this aim.

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.

Conclusion

GraphQL is a great technology to have in an organisation’s API toolkit. Whilst it is not the solution to all API design requirements, it is a great way to build over existing estate without the need for extensive re-work.

It allows front end application developers to design in a “Greenfield” manner without being constrained by the systems and data models they have to consume, and it has a thriving community and great support for frameworks such as React.

However this comes at a cost, that cost is…..difficult shifts in culture and governance.