A Case for GraphQL in an API Gateway

James Warren
Sep 12, 2017 · 3 min read
Image for post
Image for post

We love REST at SOON_, we’ve built a lot of APIs with it, often in service-oriented architectures. When I heard about GraphQL I was intrigued to see if it could solve some of the issues we’ve faced, specifically in the API gateway, which typically provides our client facing or public APIs.

Why GraphQL?

In short, the API gateway’s role is to map client requirements to a multitude of back end services within a micro-serviced system. GraphQL is built around a data schema definition, providing a framework for client queries and a runtime to execute queries on the server-side. We can use this to map services as a data graph that spans the entire system; querying across the schema as if it were a single resource, resolving the data as required in the GraphQL runtime.


I’m a big fan of self-describing APIs — switching back and forth between docs and requests when integrating can quickly become a headache. The ultimate dream is to create a browsable API for both man and machine. With HAL and HAETOS the REST paradigm comes close to the dream but in my experience it requires a lot of work to get right and ultimately incomplete links break this experience.

GraphQL APIs are organised by types and fields, opposed to individual resource endpoints — this type system enables some intelligent tooling out of the box. GraphiQL is the game changer here, providing a UI to browse the schema and interactively build and test queries; effectively bringing the documentation inline with the API.


A gateway API is distinctly different from a typical back end service; whether it’s a public API or for a specific client application, the API surface area is much greater than any individual service as it crosses many internal service boundaries and seeks to provide an abstraction over them.

In fact, the resource segmentation in the back end tends to break down in the client, where we just want object graphs with data for a specific view — this often means data collated from multiple services. In the REST world we solve this with specific endpoints and embedded HAL resources, which are defined upfront — we make assumptions about the data a client will need. It’s a nice idea but rarely stands the test of time as requirements always change.

Dynamic field serialisation is another way to provide clients with customised response objects. This is often implemented through query parameters in REST to allow the consumer to request only fields they need. However, these sparse field-sets are often not practical as it becomes tedious for implementors to continually refer to documentation on available fields. Bringing embedded resources into the mix makes the problem even more complex, as this example illustrates:

http http://api.thisisoon.com/articles/1?fields=title,summary
"title": "foo",
"summary": "bar",
"_embedded": {
"author: {...},
"relatedArticles": [...],
"tags": [...]
"_links": {...}

GraphQL’s browsable schema solves this through its ability to provide the docs inline, with schema hinting and auto-completion. This leads to a very compositional interface for building up complex object graphs in a single query.

query {
article(1) {
author {
relatedArticles(first: 10) {
tags(first: 2) {
// Response
"data": {
"article": {
"title": "foo",
"summary": "bar"
"author": {
"name": "Dude"
"relatedArticles": [
{ "title": "GraphQL" }
"tags": [
{ "name": "Tech" }


GraphQL is not a direct replacement for REST, it is a high level tool that can, given the right use case, create a great API experience. With it’s compositional interface consumers can benefit from greater flexibility. There will be times when REST is more suitable and the great thing is they can be used together.

Further Reading

SOON_ London

We design and build services, platforms and digitally…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store