Apollo Federation Connector

Fusion supports two subgraph protocols: GraphQL Federation and Apollo Federation. GraphQL Federation is the open specification (formerly the GraphQL Composite Schemas specification) that a Fusion gateway speaks directly. Apollo Federation is Apollo's model for distributed GraphQL. This page explains the Apollo Federation connector, which lets a Fusion gateway run Apollo Federation subgraphs.

The connector lets you put a Fusion gateway in front of existing Apollo Federation subgraphs without changing them. During composition, Fusion reads each subgraph's Apollo Federation SDL, detects Apollo Federation schemas, and translates them into the GraphQL Federation model. At runtime, the gateway speaks Apollo's wire protocol (the _entities field with typed representations) to Apollo Federation subgraphs. It speaks the GraphQL Federation protocol through lookup fields to GraphQL Federation subgraphs in the same graph. Your subgraphs keep their existing SDL, __resolveReference and reference resolvers, and deployment model.

There is no separate mode to enable. Detection happens per source schema, so one graph can mix Apollo Federation subgraphs (in any language: Apollo Server, HotChocolate.ApolloFederation, graphql-java, and others) with GraphQL Federation subgraphs and compose them into the composed schema.

Use this page when you want to run Apollo Federation subgraphs as they are. To move a subgraph to the GraphQL Federation protocol instead, see Coming from Apollo Federation. The two protocols interoperate, so you can move one subgraph at a time.

How the Connector Works#

The connector does two things: it translates Apollo Federation schemas at composition time, and it uses Apollo's entity protocol at runtime.

At composition time, Fusion inspects each source schema. When a schema carries the Apollo Federation @link to https://specs.apollo.dev/federation, the composer recognizes it as an Apollo Federation subgraph and runs a translation pass over it.

That pass maps Apollo Federation directives onto the GraphQL Federation model: @key becomes lookup fields, @requires becomes @require, @external fields are resolved into the model, and the Relay node field becomes a lookup. Fusion removes the Apollo Federation infrastructure types (_service, _entities, _Entity, _Any). The result is the composed schema. Clients do not see Apollo Federation directives or infrastructure types.

At runtime, when the gateway needs to resolve entity fields from an Apollo Federation subgraph, it calls that subgraph as an Apollo router would. It sends the _entities(representations: [...]) query with typed representations ({ __typename, <key fields> }) and reads the entities back. The gateway enters GraphQL Federation subgraphs through their lookup fields instead. Both paths run inside the same query plan.

Because detection happens per source schema, mixed graphs need no configuration. An Apollo Federation subgraph and a GraphQL Federation subgraph that both contribute fields to Product merge into one Product type in the composed schema.

Getting the Subgraph Schema#

Composition consumes the subgraph's Apollo Federation SDL in the exact form that the subgraph exposes through Apollo's _service field:

GraphQL

query {
  _service {
    sdl
  }
}

Pass this SDL to the composer unchanged. It is the @link-carrying document that still contains the Apollo Federation directives (@key, @requires, @external, and so on).

Translation from Apollo Federation directives to the GraphQL Federation model happens inside composition, so the SDL must reach the composer in that form. A schema that has already been stripped of its Apollo Federation directives cannot be detected as an Apollo Federation schema and cannot be translated.

Save each subgraph's _service { sdl } output to a .graphqls file, one file per subgraph. Give each file a companion <name>-settings.json that tells the gateway how to reach the subgraph at runtime. See the Schema Settings File Reference for the settings file format.

Composing an Apollo Federation Subgraph#

Compose Apollo Federation subgraphs the same way you compose GraphQL Federation subgraphs. There is no flag to set. Point nitro fusion compose at the source schema files, and the composer detects and translates Apollo Federation subgraphs automatically:

Bash

nitro fusion compose \
  --source-schema-file ./accounts/schema.graphqls \
  --source-schema-file ./reviews/schema.graphqls \
  --archive gateway.far

You can list Apollo Federation and GraphQL Federation source schema files in the same command. Composition produces a single .far archive that contains the composed schema. If a subgraph uses an Apollo Federation feature that Fusion does not yet support, composition fails with a specific error code (see Current Limitations).

For the full command reference, see nitro fusion compose. For the composition rules and the complete log-code list, see Composition.

What Translates to What#

Composition resolves Apollo Federation constructs before clients see the schema. The composed schema follows the GraphQL Federation model, so clients and downstream tools do not see Apollo Federation directives.

Apollo Federation	Handled during composition as
`@key(fields: "...")`	Generated lookup fields, one per key. Single, composite, and nested keys are supported.
`_entities` / `__resolveReference`	Kept as the runtime contract. The gateway calls them over the `_entities` protocol like a router.
`@requires(fields: "...")`	Translated to `@require`, including nested object requirements and requirement chains.
`@provides(fields: "...")`	Honored. The `@external` fields it references are kept resolvable from the providing subgraph.
`@external`	External fields are resolved into the model.
`@shareable`	Preserved. Key fields are marked shareable automatically.
`@override(from: "...")`	Preserved as override semantics.
`@inaccessible`	Preserved.
`@tag`	Preserved.
Union members contributed across subgraphs	Merged into a single union in the composed schema.

Global Object Identification#

If your Apollo Federation subgraphs implement the Relay node field (a Query.node(id: ID!): Node field over a Node interface), the connector turns it into a lookup during composition. The gateway can then resolve any Node type through that lookup.

Configure how the gateway resolves node(id:) at runtime with the NodeResolution option on FusionOptions:

Value	Behavior
`NodeResolution.Gateway`	The gateway decodes the `id`, determines the object's type from it, and routes the lookup to the source schema that owns that type. This is the default.
`NodeResolution.SourceSchema`	The gateway does not interpret the `id`. It forwards `node(id:)` to a source schema that owns a node lookup, and that subgraph resolves the type. Use this when identifiers are opaque to the gateway, which is often the case for Apollo Federation subgraphs that mint their own IDs.

Set the option on the gateway builder with ModifyOptions:

builder
    .AddGraphQLGateway()
    .ModifyOptions(options => options.NodeResolution = NodeResolution.SourceSchema)
    .AddFileSystemConfiguration("./gateway.far");

Runtime Behavior#

The gateway uses Apollo's entity protocol when it routes to Apollo Federation subgraphs.

Entity batching. When the gateway needs several entities of the same type from one subgraph, it sends one _entities call with all representations in the representations array. Identical representations are de-duplicated.

When a query plan needs several different lookups from the same subgraph, the gateway dispatches them together as one batched request.

Requirement threading. When a field on one subgraph depends on data owned by another (the @requires case), the gateway resolves the required fields first. It then threads them into the representation it sends to the subgraph that needs them.

Error propagation. Errors returned by a subgraph and transport failures that prevent the gateway from reaching it are attached to the affected result paths and surfaced in the gateway response.

Current Limitations#

The connector is under active development and ships as a preview. Composition rejects unsupported Apollo Federation features with a specific error code, so the gateway does not produce a schema that would misbehave at runtime.

Apollo Federation v1 is not supported. A subgraph must be an Apollo Federation v2 schema, which means it carries a @link to https://specs.apollo.dev/federation. A v1 subgraph (which has no such @link) is rejected with FEDERATION_V1_NOT_SUPPORTED. Upgrade the subgraph to Apollo Federation v2.
Several Apollo Federation v2 directives are not supported. Composition rejects @interfaceObject, @composeDirective, @authenticated, @requiresScopes, and @policy with FEDERATION_DIRECTIVE_NOT_SUPPORTED. Remove the directive, or express the equivalent with a GraphQL Federation construct.

Both error codes are listed in the Composition log-code reference.

Feature support tracks the GraphQL Hive federation-gateway-audit compliance suite, and the set of supported features grows as the connector passes more of that suite.

Relationship to Migrating#

The connector runs your Apollo Federation subgraphs as they are. It does not rewrite them. When you want to move a subgraph to the GraphQL Federation protocol ([Lookup] in place of @key, [Require] in place of @requires, and so on), see Coming from Apollo Federation.

You do not have to choose one protocol for the whole graph. Apollo Federation and GraphQL Federation subgraphs compose together, so you can put the gateway in front of your existing Apollo Federation fleet first. Then you can move subgraphs to the GraphQL Federation protocol one at a time while the rest keep running unchanged.

Next Steps#

Compose and run a gateway: nitro fusion compose and Getting Started.
Understand entity resolution in the GraphQL Federation model: Entities and Lookups.
Move subgraphs to the GraphQL Federation protocol: Coming from Apollo Federation.

Edit this page on GitHub