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

Enabling StepZen Subgraphs for Apollo Federation

How to Annotate StepZen GraphQL APIs for Apollo Federation

In Types of Federation we saw that Apollo uses an object-based federation model, as opposed to StepZen's query-based model.

Here we show you how you can quickly enable subgraphs built (or proxied) in StepZen for Apollo Federation.

Key Apollo Federation constructs

Let's assume that there is a type Customer that gets its data from two subgraphs:

  1. customer subgraph:
type Customer {
  id: ID!
  name: String
}
  1. order subgraph:
type Customer {
  id: ID!
  orders: [Order]
}
type Order {
  customerId: ID!
  createdOn: Date!
  totalAmount: Float!
}

Some part of Customer comes from the customer subgraph, and some from order.

To federate these two subgraphs in Apollo, each subgraph must identify how a specific Customer can be accessed, by providing two constructs:

  • Declaring the unique key for Customer (say by @key (fields: "id")).
  • Providing the right query for Apollo to execute when it has that key to get the appropriate part of the Customer object.

Apollo Federation also wants these aspects wrapped in new queries (called _service and _entities). StepZen auto-generates these queries for you.

Example: Federate StepZen customer and order subgraphs in Apollo

Let's see how this works with a real example in StepZen:

  1. customer subgraph:
type Customer {
  id: ID!
  name: String
}
type Query {
  customer (id: ID!): Customer
    @rest (...)
}
# Write the following new line in a separate file or same file
# This tells Apollo that `id` is a key field for `Customer`

extend type Customer @key(fields: "id")
  1. order subgraph:
type Customer {
  id: ID!
}
type Order {
  customerId: ID!
  createdOn: Date!
  totalAmount: Float!
}
type Query {
  orders (customerId: ID!): [Order]
    @dbquery (...)
}
# Write these four new lines in a separate file or same file
# This tells Apollo that `id` is a key field for `Customer`
# It tells StepZen that to generate `orders` for a `Customer`
# it must query `orders` passing the right parameters

extend type Customer @key(fields: "id") {
  orders: [Order]
    @materializer (query: "orders", arguments: {name: "customerId", field: "id"})
}

These five lines (one in customer subgraph, and four in order subgraph`) are all that are needed to convert StepZen graphs into being Apollo Federation ready.

For information about @materializer and other directives, see Link Types: @materializer and the StepZen Directives Reference.

Other Apollo Federation directives

Apollo Federation sometimes requires additional directives. StepZen supports these directives, but often, you do not need them:

  • @external, used to pass additional data to subgraphs outside the @key fields:
...
type Query {
  ordersAfterDate (customerId: ID!, date: Date!); [Order]
    @dbquery (...)
}
extend type Customer @key(fields: "id") {
  orders (date: Date!): [Order] @external
    @materializer (query: "ordersAfterDate", arguments: {name: "customerId", field: "id"}, {name: "date", argument: "date"})
}
  • @include and@link are not needed, StepZen automatically generates them.
  • @override: you can use this as the Apollo specifications define
  • @tag: you can use this as the Apollo specifications define
  • @inaccessible: you can use this as the Apollo specifications define

Fancier stuff

  1. If the @rest and @dbquery in the above subgraphs were to be replaced by @graphql, what you do to make them ready for Apollo Federation remains the same. In other words, you could proxy existing subgraphs (perhaps written in a way that they cannot be modified or made Apollo Federation ready anymore) and you can then make them ready in StepZen.

  2. If you are a StepZen enterprise customer, you can develop your subgraphs locally using our docker image. For production, you have the option of running your StepZen-generated subgraphs either in StepZen cloud, or in a StepZen managed service in your private cloud (VPC) or co-locations.

Additional Resources