ApolloGraphQL.HotChocolate.Federation 0.1.0

Apollo Federation for Hot Chocolate

This is a fork of HotChocolate.Federation module that aims to provide first class Apollo Federation support for HotChocolate subgraphs.

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>
    
    <PackageReference Include="HotChocolate.AspNetCore" Version="13.5.1" />
    
    <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()
    // .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();

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.

See Apollo documentation for additional Federation details.

Annotation

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

This will generate following type

type Product @key(fields: "id") {
    id: ID!
    name: String!
    description: String
}

Federation Attributes

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
• ComposeDirective applicable on schema, see @composeDirective documentation
• Inaccessible applicable on all type definitions, see @inaccessible documentation
• InterfaceObject applicable on objects, see @interfaceObject documentation
• Link applicable on schema, see @link 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 static public methods 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);
}

This will generate following type

type Product @key(fields: "id") {
    id: ID!
    name: String!
    description: String
}

Descriptor Extensions

Federation v1 directives

• ExtendsType applicable on objects, see @extends documentation
• External applicable on fields, see @external documentation
• Key(fieldset) applicable on objects, see @key documentation
• Provides(fieldset) applicable on fields, see @provides documentation
• Requires(fieldset) applicable on fields, see @requires documentation

Federation v2 directives (includes all of the v1 directives)

• ApolloTag applicable on all type definitions, see @tag documentation
• ComposeDirective(name) applicable on schema, see @composeDirective documentation
• Inaccessible applicable on all type definitions, see @inaccessible documentation
• InterfaceObject applicable on objects, see @interfaceObject documentation
• Key(fieldset, resolvable?) applicable on objects, see @key documentation
• Link(url, [import]?) applicable on schema, see @link documentation
• Shareable applicable on fields and objects, see @shareable documentation

Entity resolution

• you have to provide ResolveReferenceWith function to be able to resolve the entities

Advanced Use Cases

Generating schema at build time

See HotChocolate documentation for details on the server support for command line interface.

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();

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

See more info in CONTRIBUTING.md.

After you have your local branch set up, take a look at our open issues to see where you can contribute.

Security

For more info on how to contact the team for security issues, see our Security Policy.

License

This library is licensed under The MIT License (MIT).