Graphs

GraphQL APIs are often referred to simply as graphs. This article explains why graphs are a powerful tool for API orchestration, the different graphs you can build, and their typical use cases.

Graph overview

Graphs are powerful tools for modeling many real-world phenomena because they resemble our natural mental models and verbal descriptions of the underlying process.

Thinking in Graphs

Imagine an ecommerce scenario where your app needs to determine and display the estimated delivery date of an order. Consider all the APIs your app has to call, like User, Cart, Inventory, and Shipping services. Then consider the things or objects that the APIs deal with. These objects probably include products, prices, customers, and billing and shipping addresses. All these objects are related in some way: customers have shipping and billing addresses, products have prices, customers have products they purchased, etc.

A graph is a representation of objects and their relations. A graph of the services in this ecommerce scenario might look something like this:

Displaying estimated delivery date means chaining APIs calls in the right sequence, determining which calls you should execute in parallel for performance gains, and implementing error and retry strategies. You may also need to transform data, convert protocols between services, and handle authentication and authorization. In short, you need to orchestrate calls to your various services.

A graph is more than just a way of modeling how your data is connected—it's a way to unify and compose your data into a single API that serves all your clients. With graphs, aspects like sequencing and parallelization are handled for you by a query planner.

Instead of writing procedural code, you declaratively configure aspects like authorization and data transformations. Graph-based API orchestration means fewer round trips, cleaner client code, and APIs that are easier to maintain than a sprawl of BFFs.

Graph types

Supergraphs

Supergraphs contain one or more subgraphs. Subgraphs are separate underlying services, each responsible for a different portion of the supergraph's available data. Clients make requests to the federated graph's single entry point called the router.

The router intelligently orchestrates and distributes the request across subgraphs and returns a unified response. For a client, the request and response cycle of querying the router looks the same as querying any GraphQL server.

Here's a basic supergraph that includes two subgraphs (Products and Users):

You can also include REST services in your supergraph by using Apollo Connectors.

Because the GraphOS Router provides advantages beyond support for multiple subgraphs, you may choose to start a supergraph with just one subgraph and a router. For example, the router enables powerful features like support for Apollo Connectors, @defered queries, and straightforward metrics reporting. Learn more about GraphOS Router capabilities.

Use case

When you have a large system with multiple domains and different teams responsible for each, federated supergraphs allow each team to own and manage their part of the schema. Federation makes it easier to scale both your organization since teams can work independently, and your system because you can scale services individually.

Monographs

A monograph, or monolith, is a graph consisting of a single GraphQL service that clients query directly.

Monographs have a single GraphQL schema that represents the API's entire dataset.

Use case

When you're just starting with GraphQL and your data doesn't sit behind a REST API, a monograph is the fastest way to begin.

A monograph can continue to meet your needs if you have a small team or a relatively simple domain. As your organization grows and more teams contribute to the graph's schema, you may run into technical and logistical scaling challenges, which are harder to manage with a monograph.

Next steps

Apollo offers the following resources depending on your familiarity with GraphQL and your preferred learning modes:

• Learn more about how GraphQL enables graph-based API orchestration.

• Learn how the GraphOS Platform helps you build and scale any kind of graph.

• If you learn best by doing, build your first supergraph with the getting started guide.

• If you learn best with videos and exercises, this interactive course teaches you how to bring an existing REST API into a GraphQL API using Apollo Connectors.