Using GraphQL to connect REST Web Services not replace them!

Over the last few years, we have been replacing our website with a single page application built in ReactJS talking to web services for data. What are the things we have learnt and what would we do differently.

We had experience in building Service Oriented Architecture (SOA) including REST web services. We knew the secret for good SOA was taking time to model your application. This can then be grouped into a set of small domain specific services for simple operations.

Very quickly we hit a problem. To create an engaging web page the application had to talk to lots of services. Like data for: user info, tracking info, page domain information, dynamic links, extra modules data. To create a fast web page it had to make a few calls as possible.

So web service started to have composite responses. This usually involved calling the most relevant domain endpoint and then embedding the other information into a HAL based response.

These services were hard to write, difficult to use and even harder to maintain. The code started to have lots of conditional logic and increased coupling and cohesion. Even in the early days of the SPA and using React we talked about creating an abstraction level to aggregate web service calls so GraphQL seemed an obvious technology to investigate. Sitting in-front of our traditional web services it can connect several services together to create useful structured data.

In the past, the Person web service would have had the ability to embed the Pets into the response of a Person. There would have been flags to control this behaviour and code to enhance the response. As Person grows with many relationships this can become complex and difficult to manage. Also it is inflexible, what if I only required the Pets names or sometimes the whole domain structure.

With GraphQL we are giving the client the ability to define the data we require and the relationships to show. This splits the responsibilities for the query. The GraphQL server can manage the relationship and generate the correct queries for the web services for the Person and Pets. Leaving the web services to focus on the specific domains.

A GraphQL server is made up of 4 parts:

1. The Schema - the queries, mutations and response models that are accessible from the server. Showing relations, data types and query filters.
2. The Models - domain models that represent the areas of the schema. These have methods and fields and can talk to multiple connectors.
3. The Resolvers - mapping the interconnection between model fields and methods.
4. The Connectors - the link to the domain-specific web service. These can handle translations and caching.

An example GraphQL service https://github.com/andyianriley/star-wars-graphql-server. See how schemas, models, resolvers and connectors work together.

Follow me on twitter @andyianriley
or see andyianriley @ linkedin.