Federating subgraphs in API Connect for GraphQL

Build subgraphs in API Connect for GraphQL (or some other library or tool) and then federate them in API Connect for GraphQL to create a supergraph.

Creating a federated GraphQL API (supergraph) in API Connect for GraphQL is a two-step process. Let's start with a clean directory called federated.

  1. Create the subgraphs.

    In the federated directory, run stepzen import graphql to create two subgraphs. Run stepzen import graphql for each of the subgraphs.

    For example, you could run:

    stepzen import graphql https://customers.acme.com/graphql --name=customers-proxy

    Of course you would pick your GraphQL endpoint, which you might have built in API Connect for GraphQL, or might have built using some other technology.

    Look at the code generated: API Connect for GraphQL now has a copy of the GraphQL backend, and it uses @graphql to connect to the backend. (This is similar to the way that API Connect Essentials uses @rest to connect to REST backends, and @dbquery to connect to database backends.)

  2. Link the subgraphs.

    Now these copies (proxies) can be linked together exactly how you would link a @rest backend with another @rest (or @dbquery) backend. That is, use @materializer to connect data in one proxy with a query in another. Your schema code looks like this:

    extend type A-in-proxy-1 {
      newdata: [B-in-proxy-2]
        @materializer (query: "b-in-proxy-2")
    }

The code in your federated folder is deployed to API Connect Essentials. Now you have a supergraph that receives a request, parses it to the correct subgraphs, and combines the results.

For information about combining results with the @materializer directive, see Building a supergraph by stitching results.

Additional options

The CLI command stepzen import graphql --help gives you some other options:

  • Avoid name conflicts:

    Use --prefix=*foo* to avoid name conflicts across your subgraphs.

  • Access a protected subgraph:

    Use --header="..." to access a protected subgraph, both during import (build time) and runtime. API Connect Essentials takes that header information and moves it config.yaml to avoid leaking authentication information into the API code.

  • Link two subgraphs together multiple times:

    You can link two subgraphs together multiple times. The same type A-in-proxy-1 can be linked twice to B-in-proxy-2 (using different queries), or different types in proxy-1 can be linked to other types in proxy-2.

  • Delete queries or mutations from your supergraph:

    You can delete queries or mutations from your supergraph that you do not want to expose to supergraph users. You do not have to delete types--only the types that are accessible from the queries or mutations are visible to the supergraph users. In API Connect Essentials, you are basically manipulating text files, and this is in keeping with that philosophy.

  • Manage changes in graphs:

    Managing changes in graphs. As your subgraph changes, your supergraphs might be affected. It is a good practice to keep the imported schemas and modifications separate. That way, a re-import does not destroy changes. If you re-import and then try to deploy, our static analysis will flag issues, and you can correct them as needed. This capability is an artifact of everything being just files.