A Case for GraphQL in an API Gateway

Published in

SOON_ London

3 min readSep 12, 2017

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.

GraphQL: A query language for APIs.

GraphQL provides a complete description of the data in your API, gives clients the power to ask for exactly what they…

graphql.org

Discoverability

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.

Flexibility

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) {
    title
    summary
    author {
      name
    }
    relatedArticles(first: 10) {
      title
    }
    tags(first: 2) {
      name
    }
  }
}// Response
{
  "data": {
    "article": {
      "title": "foo",
      "summary": "bar"
      "author": {
        "name": "Dude"
      },
      "relatedArticles": [
        { "title": "GraphQL" }
      ],
      "tags": [
        { "name": "Tech" }
      ]
    }
  }
}

Conclusion

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.