Skip to content

Could GraphQL be your API platform of choice?

Managing the delivery of data to a growing collection of HTTP clients that all have their own specific requirements is not straightforward or easily managed. A commonly established practice is to provide the data via web based API applications, and if you subscribe to the REST paradigm, this can result in a growing number of APIs each with a menagerie of endpoints for your various data types and supported protocols. This can make server-side API management a headache and result in a sub-optimal experience on the client-side, where the client needs multiple calls that return generic data types – often in an asynchronous way – “get one of them, get its related stuff then get some stuff based on that, etc,. etc,.”, which has performance issues for the client and sustainability issues for the API, that is likely using extra cycles to return data that the client didn’t want in the first place. Maybe there is an alternative?

One API to rule them all?

Rarely will you find yourself facing a problem that hasn’t been faced before and this is one that the teams at Facebook took on; their solution was to develop a standard that describes a mechanism for allowing the client to decide about the data types involved and the attributes of those types that should be returned, so gone are the multiple calls to REST endpoints to be replaced, potentially by a single API call that will return all of the data necessary to build the UI at a given time. The specification is called GraphQL and is managed by the GraphQL Foundation.

The GraphQL standard describes a schema of types that can be queried, or manipulated (mutated). The client developer can define precisely what they want in a query specification that will govern the data that is returned. Importantly this does not limit the data to one type; any of the types in the schema can returned in the same response.

By way of example; restful API’s treat the data as resources; a user interface of a book seller might make the following requests on load:

1. /book/123

2. /author/456

3. /basket/

4. /recommendations/123

5. /reviews/123

Depending on whether calls are made synchronously or asynchronously this might look like:

Or

These requests would return a fixed set of attributes for each resource; everything you might want to know about a book for instance, which is likely going to be more than is needed for the job in hand.

With GraphQL this might be a single request with a query like the following. (syntax may vary)

Which would look like:

The response will only contain the requested properties of the types requested. On the server side, projections can be applied to the query to fetch only the data from the store that was requested, no redundant data is fetched or returned which is more efficient for the database, the app server and reduces network latency.

ViewModels as an alternative

But surely using a view model could achieve the same? Well yes it could, if you are in the position of knowing exactly what data is required down to the field level you could develop a view model to exactly meet your needs and you may be able to do just that, but there are some issues here: firstly you would need a separate API for each client being served – web, mobile, data service etc as each would presumably have different requirements, and secondly problems crop up when changes are required, which will need coordination between the UI, the API and possibly the data store as well. Unless you have a very small setup this also incurs a lot of communication debt which all adds up to a reduction in development velocity. You have effectively coupled the UI to the API. This is where the GraphQL approach shines – you effectively publish one API that fits all and that can be extended as required.

Developing and maturing UI

A GraphQL API can be incredibly beneficial when developing a new front-end application, it can encourage experimentation, putting decisions in the hands of the front-end team and reducing back-end change requests as the UI development progresses, the data is available and the UI can shape it as the situation requires.

Back-end Control

You have complete control of the data you that expose via GraphQL by providing types and queries, optionally allowing the ability to filter and sort the data and giving the client the ability to page data if required. You can allow the query do draw data directly from the database for some queries and employ caching solutions such as Redis for static and slowly changing data to improve performance and reduce load. You can restrict users to reading data or allow writes (mutation in GraphQL) on a type by type basis.

At some point you may take the view that the front end has matured and that it makes sense to provide a properly versioned, dedicated API that returns a precise view model, potentially providing additional performance benefits such as http caching of GET responses (GraphQL uses POST), but this is entirely optional.

At Asset Insights, in collaboration with Network Rail, we provide access to critical data related to the management of our national rail infrastructure; we use GraphQL to present data for front-end systems, back-end processes, as part of our data import solution, and for clients to use as they wish.

We are using the HotChocolate GraphQL server from ChilliCream, currently at version 13 to access multiple data sources including Azure SQL Server and MongoDB. This approach has been invaluable as the Network Rail client has a fragmented legacy IT estate and we’re orchestrating across multiple APIs, with a Data Platform supporting a number of loosely coupled applications, developed within an agile programme, each with their own modern, highly performant UIs.

Final words

Is this really for you? I would suggest thoroughly researching the subject before committing to GraphQL, read how others have used it, was it successful? A game changer? Was it worth the effort?  There are some trade-offs with GraphQL, considering the extra effort that is required to implement the server-side and the extra tooling required on the client side, plus issues relating to GraphQL’s using of HTTP POST which excludes some of the benefits provided by http caching of get requests etc. It does take more time to implement than a conventional REST API but as discussed, if nothing else it can be used as a tool of discovery, allowing an application to evolve in the early stages of its life, taking it up to maturity where it might be better served by an API returning a precisely sculpted view model via a GET request, and the UI is not the only consumer, we use GraphQL effectively within our data-processing activities and to be consumed by our clients.