Untangling Enterprise API Architecture with GraphQL

For enterprises with many microservices or legacy services, the API architecture can become tangled and hard to manage.
GraphQL can help untangle this mess by providing clients with a single endpoint where they can get all their data and interact with it uniformly. In this article, we’ll explore how GraphQL fits into enterprise API architectures and describe how to use GraphQL with your existing services.
API Architecture Is Hard to Keep Clean

It’s hard to run a modern business without APIs. They allow you to connect systems, build new features and reach customers in new ways. But they bring some challenges. For example, how do you untangle the different services that make up your enterprise? For companies with multiple microservices or legacy services, untangling the API architecture can be challenging.
You might have one service that sends emails, another that handles payments and another that handles user authentication. All these services are maintained by different parts of your organization or external parties and used across various applications.
Each of these services might have its own RESTful endpoint, or they might all be accessed through an older SOAP-based protocol. Because REST and SOAP haven’t been updated in a long time, many implementations have deviated from the specifications.
Keeping all services consistent therefore requires a lot of architectural guidance and is hard to keep clean over the years. Technologies might change, key technical employees leave your company and new ones with a different technological point of view enter. One solution to keep API architectures more consistent is GraphQL, as it requires all services to adhere to the same API specifications.
GraphQL and Enterprise API Architecture
GraphQL is a query language that allows you to describe your data requirements in a more powerful and developer-friendly way than REST or SOAP. Its composability can help untangle enterprise API architecture. GraphQL becomes the communication layer for your services. Using the GraphQL specification, you get a unified experience when interacting with your services.
Every service in your API architecture becomes a graph that exposes a GraphQL API. In this graph, everyone who wants to integrate or consume the GraphQL API can find all the data it contains.
Data in GraphQL is represented by a schema that describes the available data structures, the shape of the data and how to retrieve it. Schemas must comply with the GraphQL specification, and the part of the organization responsible for the service can keep this schema coherent.
GraphQL composability allows you to combine these different graphs — or subgraphs — into one unified graph. Many tools are available to create such a “graph of graphs.” For example, when you use StepZen, you use the same declarative approach to combine subgraphs and to build the individual subgraphs.
In other words, when you use the GraphQL SDL (Schema Definition Language), you don’t need a different technology to implement unified graphs in GraphQL for your services.
See “GraphQL Is Built for Federation, But Don’t Do It Wrong” for an excellent discussion of many of the considerations for building a “federated” graph with GraphQL.
Adopting GraphQL
At its core, GraphQL doesn’t dictate how you write your application. Instead, it specifies the shape of your data and how you can query it. Consequently, you can use GraphQL with any language or framework, if you follow its rules for querying data.
StepZen simplifies how you create a GraphQL API; for example, when you use the StepZen CLI, you can autogenerate a GraphQL API based on your service’s existing specification (REST and SOAP). The same is true for both relation- and document-based databases. So, instead of migrating all your existing services in a lengthy development process, you can start adopting GraphQL without having to write any code.