When organizations get to a certain size, they get organized around teams. Teams typically have functional responsibilities — marketing, finance, engineering and so on. APIs follow similar functional alignments; we see sets of APIs that offer up marketing functions (promotions, product descriptions, etc.), e-commerce functions (shopping carts, etc.), finance functions (order to cash, etc.). These APIs are typically independently developed by dedicated developer teams, even if organizationally they might be in the same engineering organization.

As organizations mature in their API journeys, and as GraphQL is adopted as the next wave of API technology, they realize that their REST investments must be leveraged into GraphQL APIs. The decisions on what to expose as GraphQL can either be centralized or happen on the functional teams. As teams and organizations get larger, a common pattern is for these decisions to be decentralized. So an enterprise might have a marketing GraphQL endpoint, an e-commerce GraphQL endpoint and a finance GraphQL endpoint, with each being taken care of by the respective teams.

Considerations for a Unified GraphQL Layer

However, modern digital experiences are not built on only one functional GraphQL API. An e-commerce website, for example, might combine marketing, e-commerce and logistics GraphQL APIs to name just a few. How do these different GraphQL APIs come together in one unified GraphQL layer, against which these digital experiences can be built?

There are various terms for how these functional GraphQL APIs combine into a unified layer: schema stitching and federation are the most common. Some of these terms have become associated with specific implementations, such as Apollo’s Federation. Let’s first articulate what’s needed for this unified GraphQL API to be built, and then we will talk about the various approaches.

  • There should be no business logic in this layer. It should primarily be a routing and assembly layer. In other words, and in terms of computer science, this layer has the responsibility to scatter the request to the right functional GraphQL APIs and gather the results back to return the answers.
  • The GraphQL layer must call a functional GraphQL API with the right authentication and authorization. After all, different functions can choose to implement their own mechanisms.
  • It must be able to handle common errors, including non-responsiveness.

When you look at the above considerations, there is only one difference between what this layer needs and what is needed to build any one of the functional GraphQL APIs. Which is that while the backends for the functional GraphQL APIs can be anything — REST, SOAP, databases — the backends for this layer are exclusively GraphQL. That’s it! Both the functional APIs and the unified GraphQL layer need the ability to connect multiple backends together. Both need to handle authentication and authorizations in the front and the back. Both need to handle errors and performance issues.

Now ask yourself: If a declarative approach is right for this layer, why is it not right for the functional APIs? And if it is right for the functional APIs, why is the same approach not right for this layer?.

The Same Approach for Functional APIs and the GraphQL Layer

You will likely come to the conclusion that programming your way out of the functional GraphQL APIs and yet using a declarative approach for this layer, as is proposed by Apollo, is fundamentally complicated from a skills and maintenance perspective. It is our belief that a declarative approach is better and should be used for both the functional APIs and this layer.

In StepZen, for example, any developer — whether building functional GraphQL APIs or in this layer — uses four concepts:

  • Each backend exposes a mini GraphQL subgraph. This subgraph can be automatically generated by introspection, selected from some prefabricated public endpoints, and/or authored by adding @rest, @dbquery, and @graphql constructs to hand-authored GraphQL schema files (SDL).
  • These subgraphs can be joined together by connecting a query/mutation in one subgraph with the data produced in another subgraph, using the @materializer construct.
  • A YAML configuration file that includes access control for both the API and the backend data sources. This file stays separated from the graphs above.
  • The API and the configuration are given to StepZen to run, and the system takes care of a standard way of optimizing, caching, error handling, etc. There is no infrastructure to run or manage, and we guarantee 99.99% availability for your API.

Using these four concepts, developers can leverage all the previous investments in existing APIs and infrastructure. At the same time, organizations and frontend teams get all the added benefits of having one GraphQL API for all their APIs.

This article was originally published in The New Stack: The New Stack