This is the official Apollo Federation support library for Hot Chocolate with support for Federation 1 and Federation 2 subgraphs. For backwards compatibility, it was based on HotChocolate's original Fed 1 module with added support for Fed v2. We recommend as ongoing Federation support for HotChocolate ecosystem and using to kickstart new projects.
Apollo Federation is a powerful, open architecture that helps you create a unified supergraph that combines multiple GraphQL APIs.
ApolloGraphQL.HotChocolate.Federation provides Apollo Federation support for building subgraphs in the HotChocolate ecosystem. Individual subgraphs can be run independently of each other but can also specify
relationships to the other subgraphs by using Federated directives. See Apollo Federation documentation for details.
Installation
ApolloGraphQL.HotChocolate.Federation package is published to Nuget. Update your .csproj file with following package references
<ItemGroup>
<!-- make sure to also include HotChocolate package -->
<PackageReference Include="HotChocolate.AspNetCore" Version="13.5.1" />
<!-- federation package -->
<PackageReference Include="ApolloGraphQL.HotChocolate.Federation" Version="$LatestVersion" />
</ItemGroup>
After installing the necessary packages, you need to register Apollo Federation with your GraphQL service.
var builder = WebApplication.CreateBuilder(args);
builder.Services
.AddGraphQLServer()
.AddApolloFederationV2()
// register your types and services
;
var app = builder.Build();
app.MapGraphQL();
app.Run();
If you would like to opt-in to Federation v1 schema, you need to use .AddApolloFederation() extension instead.
Usage
Refer to HotChocolate documentation for detailed information on how to create GraphQL schemas and configure your server.
Apollo Federation requires subgraphs to provide some additional metadata to make them supergraph aware. Entities are GraphQL objects that can be uniquely identified across
the supergraph by the specified @keys. Since entities can be extended by various subgraphs, we need an extra entry point to access the entities, i.e. subgraphs need to
implement reference resolvers for entities that they support.
All federated directives are provided as attributes that can be applied directly on classes/fields/methods.
[Key("id")]
public class Product
{
public Product(string id, string name, string? description)
{
Id = id;
Name = name;
Description = description;
}
[ID]
public string Id { get; }
public string Name { get; }
public string? Description { get; }
// assumes ProductRepository with GetById method exists
// reference resolver method must be public static
[ReferenceResolver]
public static Product GetByIdAsync(
string id,
ProductRepository productRepository)
=> productRepository.GetById(id);
}
Map applicable on entity resolver method paramaters, allows you to map complex argument to a simpler representation value, e.g. [Map("foo.bar")] string bar
ReferenceResolver applicable on public static methods within an entity class to indicate entity resolver
Code First
Alternatively, if you need more granular control, you can use code first approach and manually populate federation information on the underlying GraphQL type
descriptor. All federated directives expose corresponding methods on the applicable descriptor.
public class Product
{
public Product(string id, string name, string? description)
{
Id = id;
Name = name;
Description = description;
}
[ID]
public string Id { get; }
public string Name { get; }
public string? Description { get; }
}
public class ProductType : ObjectType<Product>
{
protected override void Configure(IObjectTypeDescriptor<Product> descriptor)
{
descriptor
.Key("id")
.ResolveReferenceWith(t => GetProduct(default!, default!));
}
private static Product GetProduct(
string id,
ProductRepository productRepository)
=> productRepository.GetById(upc);
}
var builder = WebApplication.CreateBuilder(args);
builder.Services
.AddGraphQLServer()
.AddApolloFederationV2()
// register your types and services
;
var app = builder.Build();
app.MapGraphQL();
app.RunWithGraphQLCommands();
You can then generate your schema by running
dotnet run -- schema export --output schema.graphql
@composedDirective usage
By default, Supergraph schema excludes all custom directives. The `@composeDirective`` is used to specify custom directives that should be preserved in the Supergraph schema.
ApolloGraphQL.HotChocolate.Federation provides common FederatedSchema class that automatically includes Apollo Federation v2 @link definition. When applying any custom
schema directives, you should extend this class and add required attributes/directives.
When applying @composedDirective you also need to @link it your specification. Your custom schema should then be passed to the AddApolloFederationV2 extension.
[ComposeDirective("@custom")]
[Link("https://myspecs.dev/myCustomDirective/v1.0", new string[] { "@custom" })]
public class CustomSchema : FederatedSchema
{
}
var builder = WebApplication.CreateBuilder(args);
builder.Services
.AddGraphQLServer()
.AddApolloFederationV2(new CustomSchema())
// register your types and services
;
var app = builder.Build();
app.MapGraphQL();
app.Run();
@interfaceObject usage
Apollo Federation v2 supports entity interfaces, a powerful extension to the GraphQL interfaces that allows you to extend functionality of an interface across the supergraph
without having to implement (or even be aware of) all its implementing types.
In a subgraph defininig the interface we need to apply @key
[InterfaceType]
[KeyInterface("id")]
public interface Product
{
[ID]
string Id { get; }
string Name { get; }
}
[Key("id")]
public class Book : Product
{
[ID]
public string Id { get; set; }
public string Name { get; set; }
public string Content { get; set; }
}
We can then extend the interface in another subgraph by making it a type, applying @interfaceObject and same @key directive. This allows you add new fields to every
entity that implements your interface (e.g. adding Reviews field to all Product implementations).
[Key("id")]
[InterfaceObject]
public class Product
{
[ID]
public string Id { get; set; }
public List<string> Reviews { get; set; }
}
Providing subgraph contact information
You can use the @contact directive to add your team's contact information to a subgraph schema. This information is displayed in Studio, which helps other teams know who
to contact for assistance with the subgraph. See documentation for details.
We can apply [Contact] attribute on a custom schema. You then need to include @contact directive definition and pass your custom schema to the AddApolloFederationV2 extension.
[Contact("MyTeamName", "https://myteam.slack.com/archives/teams-chat-room-url", "send urgent issues to [#oncall](https://yourteam.slack.com/archives/oncall)")]
public class CustomSchema : FederatedSchema
{
}
var builder = WebApplication.CreateBuilder(args);
builder.Services
.AddGraphQLServer()
.AddType<ContactDirectiveType>();
.AddApolloFederationV2(new CustomSchema())
// register your types and services
;
var app = builder.Build();
app.MapGraphQL();
app.Run();
undefined
Migration Guide
Migrating from HotChocolate.Federation to ApolloGraphQL.HotChocolate.Federation is easy. Simply update your package import to point to a new module
<ItemGroup>
<!-- make sure to also include HotChocolate package -->
<PackageReference Include="HotChocolate.AspNetCore" Version="13.5.1" />
<!-- federation package -->
- <PackageReference Include="HotChocolate.ApolloFederation" Version="$LatestVersion" />
+ <PackageReference Include="ApolloGraphQL.HotChocolate.Federation" Version="$LatestVersion" />
</ItemGroup>
and update namespace imports
- using HotChocolate.ApolloFederation;
+ using ApolloGraphQL.HotChocolate.Federation;
While we tried to make migration process as seamless as possible, we had to make few tweaks to the library. Due to the dependency on some of the internal APIs, we had to make following breaking changes to the library:
[Key] is now applicable only on classes and you no longer can apply it on individual fields
[ReferenceResolver] is now applicable only on public static methods within an entity, it is no longer applicable on classes
Contact
If you have a specific question about the library or code, please start a discussion in the Apollo community forums or start a conversation on our Discord server.
Contributing
To get started, please fork the repo and checkout a new branch. You can then build the library locally by running
# install dependencies
dotnet restore
# build project
dotnet build
# run tests
dotnet test
