v1.0.0

Apollo Federation for HotChocolate

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.

Generating Federated Schemas

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. You need to opt-in to Federation v1 or v2 schema by invoking corresponding builder extension

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddGraphQLServer()
    // .AddApolloFederation() // use this instead if you want to opt-in to fed v1 
    .AddApolloFederationV2() 
    // register your types and services
    ;

var app = builder.Build();
app.MapGraphQL();
app.Run();

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. 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. Example attribute usage

[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);
}

Federation v1 directives

• Extends applicable on objects, see @extends documentation
• External applicable on fields, see @external documentation
• Key applicable on objects, see @key documentation
• Provides applicable on fields, see @provides documentation
• Requires applicable on fields, see @requires documentation

Federation v2 directives (includes all of the v1 directives)

• ApolloTag applicable on schema, see @tag documentation
• ApolloAuthenticated (since v2.5) applicable on enum, field, interface and object, @authenticated documentation
• ComposeDirective (since v2.1) applicable on schema, see @composeDirective documentation
• Contact applicable on schema, see @contact usage
• Inaccessible applicable on all type definitions, see @inaccessible documentation
• InterfaceObject (since v2.3) applicable on objects, see @interfaceObject documentation
• KeyInterface applicable on interfaces, see entity interface @key documentation
• Link applicable on schema, see @link documentation
• RequiresScopes (since v2.5) applicable on enum, field, interface and object, @requiresScopes documentation
• Shareable applicable on schema, see @shareable documentation

Entity resolution

• 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