Federation plugin
A plugin for building subGraphs that are compatible with Apollo Federation 2.
Usage
This page will describe the basics of the Pothos API for federation, but will not cover detailed information on how federation works, or what all the terms on this page mean. For more general information on federation, see the official docs
Install
You will need to install the plugin, as well as the directives plugin (@pothos/plugin-directives
)
and @apollo/subgraph
You will likely want to install @apollo/server as well, but it is not required if you want to use a different server
Setup
Defining entities
Defining entities for you schema is a 2 step process. First you will need to define an object type
as you would normally, then you can convert that object type to an entity by providing a key
(or
keys
), and a method to load that entity.
keys
are defined using builder.selection
. This method MUST be called with a generic argument
that defines the types for any fields that are part of the key. key
may also be an array.
resolveReference
will be called with the type used by the key
selection.
Entities are Object types that may be extended with or returned by fields in other services.
builder.asEntity
describes how the Entity will be loaded when used by another services. The key
select (or selection) should use the types of scalars your server will produce for inputs. For
example, Apollo server will convert all ID fields to string
s, even if resolvers in other services
returns IDs as numbers.
Extending external entities
External entities can be extended by calling builder.externalRef
, and then calling implement on
the returned ref.
builder.externalRef
takes the name of the entity, a selection (using builder.selection
, just
like a key
on an entity object), and a resolve method that loads an object given a key
. The
return type of the resolver is used as the backing type for the ref, and will be the type of the
parent
arg when defining fields for this type. The key
also describes what fields will be
selected from another service to use as the parent
object in resolvers for fields added when
implementing the externalRef
.
To set the resolvable
property of an external field to false
, can use builder.keyDirective
:
Adding a provides directive
To add a @provides
directive, you will need to implement the Parent type of the field being
provided as an external ref, and then use the .provides
method of the returned ref when defining
the field that will have the @provides
directive. The provided field must be listed as an
externalField
in the external type.
Building your schema and starting a server
For a functional example that combines multiple graphs built with Pothos into a single schema see https://github.com/hayes/pothos/tree/main/packages/plugin-federation/tests/example
Printing the schema
If you are printing the schema as a string for any reason, and then using the printed schema for
Apollo Federation(submitting if using Managed Federation, or composing manually with rover
), you
must use printSubgraphSchema
(from @apollo/subgraph
) or another compatible way of printing the
schema(that includes directives) in order for it to work.
Field directives directives
Several federation directives can be configured directly when defining a field includes
@shareable
, @tag
, @inaccessible
, and @override
.
For more details on these directives, see the official Federation documentation.
interface entities and @interfaceObject
Federation 2.3 introduces new features for federating interface definitions.
You can now pass interfaces to asEntity
to defined keys for an interface:
You can also extend interfaces from another subGraph by creating an interfaceObject
:
See federation documentation for more details on interfaceObject
s
composeDirective =
You can apply the composeDirective
directive when building the subgraph schema: