Declarative GraphQL Federation

The only declarative approach for federated access to data

GraphQL federation is a critical element of your GraphQL architecture. Federation is about assembling the work of independent teams (with GraphQL APIs (subgraphs) that represent their domain(s)) into one consolidated GraphQL API (supergraph). Different teams can work independently on subgraphs and the federation layer composes the subgraphs without complex logic.

Frontends query only the supergraph no matter how the subgraphs are connected behind it. Each backend team or domain can build and maintain its own subgraph(s) independently.

A declarative and query-based stitching approach

We believe that the supergraph, like the subgraphs, is better when assembled declaratively - leading to concise intuitive code and built-in runtime optimizations. There are two approaches for stitching graphs together — one based on queries, the other based on objects. StepZen uses the query-based stitching model in a simple declarative way because it delivers advantages from code, performance, and governance perspectives.

Composing Supergraphs in StepZen

You can create a GraphQL API declaratively using simple directives. For example, you can compose an API from REST and database backends using @rest and @dbquery directives. You can federate graphs with @graphql. And you can link types across subgraphs with @materializer.

The following code builds a supergraph from two subgraphs. We import the schema for each subgraph, and a query/mutation against either gets routed to the right subgraph.

Import the schema for each of the subgraphs

> stepzen import graphql https://graphql.acme.com/customers --name=customer-proxy
> stepzen import graphql https://graphql.acme.com/orders --name=order-proxy

Compose a supergraph from two subgraphs
To compose a supergraph from the two subgraphs, write a new file that contains the following code.
```
extend type Customer {
     orders: [Order]
         @materializer (query: “orders”, arguments: {name: “customerId”, field: “id”})
}
```
This uses @materializer to link types across subgraphs. Specifically, this code tells StepZen to get Customer.orders by issuing a query against order-proxy.orders and passing the value of the field Customer.id into its argument customerId.
Fetch the data from each of the subgraphs and link them
Here's the query to fetch data from each subgraph and link them.
```
{ customer (email: “john.doe@example.com”) {name orders {createdAt carrier}}}
```

Federate Subgraphs Created with Other Technology

Have an existing GraphQL API, written in a non-StepZen library or technology like Rust, Java, Kotlin etc.? You can federate that subgraph into StepZen using the StepZen command: stepzen import graphql.

Two StepZen graphs being federated into a single GraphQL API — Federate subgraphs in StepZen

Creating a supergraph in StepZen is similar to creating a subgraph. For subgraphs, you typically use @rest and @dbquery to connect to REST and database backends. For supergraphs, you use @graphql to connect GraphQL backends. As your teams evolve, you can easily break apart a graph and keep existing code.

Declaratively Build a Supergraph in StepZen

A declarative approach: Simpler code and better runtime characteristics

StepZen's' approach to federation delivers concisely coded, performance-optimized, well-governed, and secured federation implementations. Because the graphs are built and stitched declaratively, StepZen can do optimizations like 1 + N, caching, pushdowns, etc. This is recursively true if the subgraphs are built with StepZen. StepZen’s federation model has a number of other advantages.

EVOLUTION | Going from one team to a “team of teams” is trivial. You keep the @materializer code aside, split the rest of the code, create two subgraphs out of it, proxy the subgraphs using stepzen import graphql, and throw your stitching code back in the federation layer. Nothing changes.

INDEPENDENCE OF CONCERNS | Each subgraph GraphQL service is blissfully unaware of the other. The orders subgraph does not know that it is being federated into the customer subgraph. The only thing that subgraph should care about is what API it exposes further up the chain. How that API is used to federate is not its concern. Keeps the n-square problem from happening.

PERFORMANCE | The declarative approach allows StepZen to analyze and optimize the execution of the subqueries. We can batch the queries as needed for subgraphs (we detect whether these subqueries take singletons or a batch), and we can and do insert caching at various layers.

GOVERNANCE | Each subgraph can have its own naming convention. It can have its own authorization/authentication. Because StepZen has sophisticated @rest capabilities and our @graphql is a layer on top of @rest, we can be flexible in mapping different structures, names, and access controls into the federation layer.

SECURITY | GraphQL implementations (including StepZen’s) have some powerful security mechanisms for governing who can call what queries with what parameters. Query-based stitching automatically and easily uses the same mechanisms to protect the edges. In contrast, object-based stitching must implement this at the special @key resolver level, requiring entirely new mechanisms, which are typically not easily built.

Composing Supergraphs in Apollo

Apollo is a powerful federation engine. It uses object-based stitching and requires each of the subgraphs to fully support _service and _entities query type. StepZen is Apollo Federation 2 compatible, which means that with a few simple annotations on subgraphs created in StepZen, you can federate them in Apollo.

Let's use the two subgraphs (customers and orders) from our example above and explore how to enable them for Apollo Federation.

https://graphql.acme.com/customers
https://graphql.acme.com/orders

Annotate the customer subgraph
Add the following code in the customer subgraph.
```
extend type Customer @key(fields: “id”)
```

Annotate the orders subgraph

And the following code in the orders subgraph.

type Customer @key (fields: “id”) {
     id: ID!
     orders: [Order]
         @materializer (query: “orders”, arguments: {name: “customerId”, field: “id”})
}

Those annotations are all that is needed to make the two subgraphs ready for federation in Apollo.

Proxy Subgraphs Created with Other Technology

Have an existing subgraph, written in a library or technology that is not Apollo Federation ready? You can proxy that subgraph into StepZen using the StepZen CLI: stepzen import graphql. Then you can annotate the proxy with @key and other Apollo annotations (as above). Your legacy graph is now Apollo Federation ready.

Two StepZen graphs being federated into a single Apollo Federation API — Federate subgraphs in Apollo

How to Enable Subgraphs in StepZen for Apollo Federation

GraphQL Federation Your Way

GraphQL Federation is a central concept in GraphQL (and in fact is one of the superpowers of GraphQL in a way that REST APIs can never do). Declaratively building the federated supergraphs is the approach that gives you the most flexibility and choice in the federation layer.

In StepZen (using some very simple constructs that keep the code clean), and how you decide what to federate and what to not federate is entirely up to you – the same declarative software approach works at both levels.
In Apollo - building or proxying the subgraphs in StepZen and easily annotating them to plug into the Apollo Federation layer.

The choice is yours. Let's begin!