Auto generated GraphQL Gateways bring your REST APIs together, for great and for better!

Introduction

In this article, we want to introduce a GraphQL Gateway approach that allows developers to auto-generate a high level GraphQL query interface on top of traditional REST based services that use Swagger / OpenAPI as documentation format.

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

What is GraphQL?

“GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.”

Read more about it: https://graphql.org/

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:

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.

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 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.

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?

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

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.

“Specially for those who had to deal with the pain of manually implementing a large GraphQL code base…”

---

Auto generated GraphQL Gateways bring your REST APIs together, for great and for better! was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.

This content was originally published here.