Skip to main content
Version: AMF v5.x.x

GraphQL Federation

Summary​

AMF supports APIs defined as GraphQL Subgraph APIs compliant with the Apollo Federation v2 spec

info

The Apollo Federation v2 spec has been revised since the revision mentioned in the above link.

No explicit mentions on backwards compatibility between Apollo Federation v2 spec revisions are mentioned in the Apollo documentation. We assume Apollo Federation v2 spec revisions are backwards compatible.

To get started with Federation you should use the GraphQLFederationConfiguration

AMF Federation Model​

The AMF Federation model contains the required information to Federate both GraphQL and Rest APIs. In GraphQL this comes in the form of federating Shapes while in REST APIs federating Operations.

Below is a list of the relevant model parts. Please refer to the linked documentation for each case for more information.

Key​

Contains the information from keys that identify federated Shapes or Operations (@key directive in Apollo, read "Note on Apollo _FieldSet DSL")

FederationMetadata​

Contains different kinds of metadata from a federated Shape or Operation. Each of this has it own federation metadata, ShapeFederationMetadata and OperationFederationMetadata respectively.

Some properties:​

Note on Apollo _FieldSet DSL​

Apollo allows to use the Value GraphQL construct to reference fields that make up a key. This construct is a tree. In AMF such construct is flattened and represented as a sequence of PropertyShapePath where each PropertyShapePath represents the traversal from the root of the tree to each of the leaf nodes.

Parsing support​

AMF supports parsing APIs defined as GraphQL Subgraphs compliant with the Apollo Federation v2 spec. Federation directives are supported out of the box without having to declare them nor import them with the @link directive.

Federation directives are parsed differently from other directives. Non-federation directive applications will be parsed as DomainExtensions and their corresponding declaration as CustomDomainProperty. Federation directives are parsed instead as part of the Federation model.

Supported directives​

  • @external
  • @requires
  • @provides
  • @key
  • @shareable
  • @inaccessible
  • @override

Non parsed directives​

These directives do not require declaration. Parsing these will produce no effect on the output AMF model.

  • @link

Not supported directives​

These directives require declaration despite being part of the Apollo Federation v2 spec. Support for these will be added in subsequent AMF releases.

  • @tag
  • @composeDirective
  • @extends: AMF supports the built in extend GraphQL keyword so it is not necessary to use this directive

Transformation support​

The GraphQLFederationConfiguration provides the following transformation pipelines:

  • Editing: transforms a parsed GraphQL Subgraph API into the AMF canonical model with ID shortening
  • Cache: transforms a parsed GraphQL Subgraph API into the AMF canonical model without ID shortening
  • Introspection: transforms a parsed GraphQL Subgraph API into the model obtained from performing introspection on a running instance of such GraphQL Subgraph API. Follows the steps under the buildSubgraphSchema function in Apollo

Validation support​

Federation introduces stricter validations then GraphQL. The GraphQLFederationConfiguration is capable of validating such stricter constraints. Examples of these are:

  • @key directive must point to existing properties
  • Fields targeted by @requires should be annotated as @external
  • Fields targeted by @provides should be annotated as @external
  • Cannot declare types nor fields with reserved federation names like _FieldSet, _Entity, _Service, _entities and _service