Why GraphQL is so important for distributed systems?

When building distributed systems such as micro-services, we tend to create dozens and even hundreds of HTTP and Event based services as part of our solutions implementation.

Distributed systems are great and they are here to stay!

However, distributed systems and specially distributed APIs, are also hard to manage.

Next, with the help of some diagrams I want to focus on the complexity of dealing with data aggregations from a client perspective:

A. Internet facing clients talking directly to every domain API

In the diagram above, internet facing clients (aka our websites or mobile apps) have the responsibility to request and merge separately domain independent pieces of data. This design should be avoided at all cost, because it brings a lot of business logic to the client-side and performance penalisations due to network latencies.

B. Internet facing clients talking directly to proxy APIs who manages data aggregations and downstream relations.

This design is more efficient for API consumers, as proxy APIs take care of data aggregations. For example, it would take one client request to fetch User and Comments entities and their relations.

However, on the backend side this design would soon become hard to maintain. There are two major reasons to avoid this architecture:

The more downstream services are added or updated, the more difficult is to keep track of the changes and integrations in the upper proxy layer.

Because proxy APIs copy downstream services interfaces and extend them, developers will have to deal with a lot of duplicated source code.

C. Internet facing clients talk directly and only to the GraphQL Gateway who manages the global API contracts and data aggregations.

GraphQL improves everything:

Good fit for complex systems and microservices. …

Fetching data with a single API call. …

No over- and under-fetching problems. …

Tailoring requests to your needs. …

Validation and type checking out-of-the-box. …

Autogenerating API documentation. …

API evolution without versioning. …

Code-sharing.

The problem of manually maintaining a GraphQL gateway

While GraphQL harmonizes the access to your data, downstream services are primarily implemented using REST.

So, when types, queries, mutations and resolvers have to be manually written and maintained for a large distributed system, things start to get messy.

The gql-gateway library to the rescue

The gql-gateway open-source library for Node.js provides a GraphQL Gateway that allows the interaction with Swagger/OpenAPI based REST APIs, by autogenerating and merging their GraphQL schemas. 🚀

Through this gateway, it is possible to easily establish aggregations between the downstream REST services using GraphQL generated types, queries and mutations.

This library was created at ShareNow to simplify and actually automate the creation of GraphQL Gateways on top of REST based micro-services. Most of the development was in charge of Ivan Martinez Pupo, a Senior Software Engineer at ShareNow 👏

How this library actually works?

Read and parse Swagger/OpenAPI specifications from all given downstream services. For each specification auto-generate the GraphQL Types, Queries and Mutations; as well as auto-generate the APIs based resolvers. Merge our local GraphQL definitions containing custom aggregations and extensions along with the previous generated schemas. Run everything using an Apollo Server.

What to give it a try?

const gateway = require('gql-gateway') const endpointsList = [{

name: 'petstore_service',

url: 'https://petstore.swagger.io/v2/swagger.json'

}, {

name: 'fruits_service',

url: 'https://api.predic8.de/shop/swagger'

}] gateway({ endpointsList })

.then(server => server.listen(5000))

.then(console.log('Service is now running at port: 5000'))

.catch(err => console.log(err))

NOTE: Advanced use cases are described in the project documentation https://github.com/segpacto/gql-gateway/blob/master/Readme.md

Conclusions

GraphQL sounds magic, and probably your frontend engineer colleague will say it is magic. But, on the backend, things get messy when we need to manage dozens of micro-services that use REST as their primary communication interface.

In this article we have introduced gql-gateway, a Node.js library that allows you to automate the creation of GraphQL gateways with almost no code.