StepZen is now part of IBM. For the most recent product information and updates visit our
IBM product page.

Enable Subgraphs in StepZen for Apollo Federation

Apollo + StepZen

To assemble a unified GraphQL API (supergraph) from multiple subgraphs, teams can break their single monolithic graph into slices (subgraphs) that can be independently owned by each team and released on their own schedules, without breaking the clients.

Because we believe that the supergraph, like the subgraphs, is better when assembled declaratively, you can build subgraphs and supergraphs in the same declarative fashion. StepZen supports two ways of implementing a supergraph:

  • Build subgraphs and supergraphs in StepZen — and run in StepZen. See Declarative GraphQL Federation
  • Build (or proxy) subgraphs in StepZen, and supergraphs in Apollo — and run in Apollo

Quickly Enable Subgraphs Built or Proxied in StepZen for Apollo Federation

Hand-crafting a GraphQL server to implement a subgraph that must access data from data sources like REST, SQL, NoSQL, SOAP / XML, etc.can be time consuming and error prone. With StepZen, you can quickly assemble subgraphs using one of two methods and connect them using StepZen's @materializer directive.

  • Let StepZen introspect the backend service (REST, SOAP/XML, database or GraphQL) and generate your GraphQL schema for you. All via a CLI command:stepzen import [curl | mysql | postgresql]
  • Write your schema(SDL file) and attach @rest,@dbquery or @graphql directives to specify data connectivity and execution.
  • Use @materializer to connect subgraphs and extend them with the @key directive required for Apollo Federation.
  • Easily enable Apollo Federation capabilities like@external and @requires.

Why Build Your Subgraphs with StepZen?

Whether you want to build new subgraphs quickly, or proxy existing subgraphs that you do not want to modify, StepZen can significantly accelerate your development and deliver subgraphs ready for the Apollo Federation layer.

While Apollo leaves the choice of how you build subgraphs up to you, there are advantages of doing it using StepZen.

  • Speed of development A few lines of code gets you a subgraph against any backend.
  • Optimized backend access StepZen is a specialized in-memory GraphQL query optimization engine, with in-memory JSON stitching, built by database experts.
  • No code changes required to enable Apollo FederationSometimes the GraphQL backend that you want to federate is from a software provider that you do not have control over; sometimes your teams has build their subgraphs using libraries that have no support for Apollo Federation. Either way, a simplestepzen import graphql command allows you to create a proxy layer in StepZen that then easily enables your backend for Apollo Federation.
  • Run your subgraphs in the StepZen cloud You get high performance because the REST, database and GraphQL calls are all optimized for efficiencies — with built-in caching, pushdowns and scaling.

How to Build & Enable Subgraphs for Apollo Federation

Whether you let StepZen introspect the backend service (REST, SOAP / XML, database or GraphQL), or you write your SDL and attach@rest, @dbquery or @graphqldirectives to it, you get a compact code that represents the GraphQL-ization of a backend or domain.

Build your subgraphs with a few lines of declarative code

StepZen’ s directives take away much of the heavy lifting for you, the entirety of the two blocks of code below(Customers subgraph and Orders subgraph) represents two GraphQL APIs :

Customers subgraph (equivalently created with thestepzen import curl https://api.acme.com/customerscommand

type User {
  id: ID
  name: String
  email: String
}
type Query {
  userByEmail (email: String): User
      @rest (endpoint: “https://api.acme.com/customers?email=$email”)
  userById (id: ID): User
      @rest (endpoint: “https://api.acme.com/customers/$id”)
}

Orders subgraph (equivalently created with thestepzen import postgresql command)

type Order {
  id: ID
  createdOn: Date
  carrier: String
  trackingId: String
}
type Query {
  orders (customerId: ID): [Order]
      @dbquery (type: “postgresql”, table: “orders”)
}

Extend your subgraphs with the @keydirective

StepZen’s non-root resolvers use a directive@materializer. To see how it works, let's extend our Customers and Orders subgraphs with the @key directive that Apollo Federation requires.The code looks like this:

Customers subgraph with @key annotation

type User @key (fields: “id”){
  id: ID
  name: String
  email: String
}
type Query {
  userByEmail (email: String): User
      @rest (endpoint: “https://api.acme.com/customers?email=$email”)
  userById (id: ID): User
      @rest (endpoint: “https://api.acme.com/customers/$id”)
}

Orders subgraph with@keyannotation

type User @key (fields: “id”) {
  id: ID
  orders: [Order]
    @materializer (query: “orders”,
                    arguments: [{name: “customerId”, field: “id”}])
}
type Order {
  id: ID
  createdOn: Date
  carrier: String
  trackingId: String
}
type Query {
  orders (customerId: ID): [Order]
      @dbquery (type: “postgresql”, table: “orders”)
}

The Orders subgraph shows that to populate User.orders, we issue the query orders and pass inUser.id as the argument customerIdfor that query. (You can also attach a series of transformations if needed.)

Non-root resolvers are created by @materializer that connects the data in the enclosing type (its scalar fields are always produced first in the execution step) with a query/mutation, which in turn returns the data of the type of that field being resolved.

Apollo Federation Subgraph Compatibility

In addition to @key, subgraphs created (or proxied) in StepZen support the following annotations for Apollo Federation 1 and Apollo Federation 2. See the Apollo Federation docs for latest compatability information and the StepZen & Apollo Federation Example for a tutorial with details about annotating StepZen subgraphs for Apollo Federation.

StepZen Apollo compatibility Matrix

Example Code

Let's get started!

Follow the instructions in the stepzen-dev/examples repo to create two subgraphs in StepZen and federate them in Apollo. Our example subgraphs are:

  • Customers - Data from a MySQL backend provides customer information
  • Returns - Data from a REST API backend provides the locations where a customer can return goods shipped to them

We federate them so that a single query can get the "returns locations" close to a customer's address. The example uses Apollo's managed federation, which in turn means that the supergraph's definition is maintained in your Apollo account.

Example showcase two subgraphs built in StepZen, federated in Apollo