Declarative GraphQL Federation

Simplicity. Evolution. Choice.

A federated GraphQL API (supergraph) brings together different services (subgraphs) into a single unified API endpoint. Different teams can work independently on subgraphs and the federation layer handles the hard part of composing 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 Matter of Choice

Using StepZen you can build subgraphs and supergraphs in the same declarative fashion. We believe that the supergraph, like the subgraphs, is better when assembled declaratively - leading to concise intuitive code and built-in runtime optimizations. We also believe that choice is important. After all, your environment might demand that you do things differently. StepZen supports two ways of implementing a supergraph.

Build subgraphs and supergraphs in StepZen — and run in StepZen
Build (or proxy) subgraphs in StepZen, and supergraphs in Apollo — and run in Apollo

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.

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

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

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.

How to Enable Subgraphs in StepZen for Apollo Federation

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

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). We believe that declaratively building the federated supergraphs is the right approach. It 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!

Build Quicker. Run Better.

Successful GraphQL Implementations wherever your data lives.

Request a Demo