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!

Sign Up

Build Quicker. Run Better.

Successful GraphQL Implementations wherever your data lives.

Request a Demo

This site uses cookies: By using this website, you consent to our use of cookies in accordance with our Website Terms of Use and Cookie Policy.