Federated GraphQL Subscriptions

Late last year we announced support for Federated Graphs. Today, we're excited to share our latest enhancement to Federated Graphs: GraphQL subscription support.

Subscriptions allow you to add real-time features into your GraphQL API, notifying any subscribers whenever an event they're interested in occurs. We think this pairs well with Federation - whenever an event occurs in one of your subgraphs you can automatically augment that event with data from your other subgraphs.

For example if you were building a backend for an order processing system you might have an orders subgraph, a users subgraph and a products subgraph. In this hypothetical system your users subgraph would expose a User entity with an id key, and the products subgraph could expose a Product entity with an sku key, something like this:

type Product @key(id: "sku") {
  sku: ID!
  name: String!
  description: String!
}

You might then want to build a UI that notified warehouse workers of new orders as they come in, perhaps via a newOrders subscription. But you might not want to complicate your order subgraph with all of the specifics of products or users. Instead you could use federation to link the Order to its related entities, something like this:

type Subscription {
  newOrders: NewOrder!
}

type NewOrder {
  id: ID!
  products: [Product]!
  user: User!
}

extend type Product @key(id: "sku", resolvable: false) {
  sku: ID!
}

extend type User @key(id: "id", resolvable: false) {
  id: ID!
}

If you load all these subgraphs up into a Federated Graph, your warehouse UI would be able to make a single subscription call to see all of the data associated with an order in real time:

subscription {
  newOrders {
    id
    products {
      sku
      name
    }
    user {
      address
    }
  }
}

GraphQL Subscriptions have different behaviour from queries and mutations - they don't necessarily return any data immediately and you'd usually expect to receive more than one response per subscription. As a result, they need different transport implementations from the standard GraphQLOverHttp transport.

Currently Grafbase supports:

• GraphQL over Server-Sent Events (in distinct connections mode) for incoming subscription calls.
• GraphQL over WebSocket is currently always used to talk to subgraphs, and can be used to for incoming calls to our CLI or self hosted Grafbase. Note that this is not yet supported in our managed offering.
• Incremental Delivery can also be used for incoming calls but is not recommended.

Pathfinder has also been updated with support for subscriptions using the server-sent events transport as part of this project.

Stay tuned for further updates and enhancements as we continue to innovate and support your development journey with Grafbase.

We'd love to hear your feedback and ideas, so join us on Discord.