Federation Architecture

Introduction

Federation in Hasura DDN upgrades how you build and manage your API.

It is the process of combining multiple subgraphs with multiple data sources into a single supergraph to create a unified GraphQL API that provides access to all your data domains through a single endpoint.

When coupled with the collaboration features in Hasura DDN, this architecture enables more collaborative workflows and allows teams to independently develop and deploy subgraphs while maintaining strong governance over the development process.

DDN Advanced plan required

Independent subgraph development is only available on the DDN Advanced plan.

Benefits

• Modular Development: Subgraphs promote modular development by allowing teams to independently develop, test, and deploy their code without impacting the functionality of other subgraphs. This can also be done in independent repositories for each subgraph, in a "multi-repo" setup. This modular approach simplifies code management and reduces the risk of breaking changes. Subgraphs can be tested in context of the full supergraph to ensure that they work as expected when combined.
• Independent Deployment: Subgraphs can also be deployed individually, ensuring that updates to one subgraph do not require downtime for the entire supergraph. This flexibility allows for continuous integration and delivery (CI/CD) practices that accelerate feature releases.
• Improved Collaboration: Subgraphs allow different teams to focus on their specialized data domains, fostering collaboration by enabling them to share their APIs and data through a unified interface. This collaborative but isolated workflow environment accelerates development times and reduces friction between teams.
• Strong Governance: Hasura DDN provides robust governance features, such as project collaboration roles and permissions that ensure data integrity and security across subgraphs. These features enable teams to enforce data policies and restrictions, protecting sensitive information and maintaining compliance with regulatory requirements.
• Efficient Data Management: Federation simplifies data management by enabling teams to work with smaller, more manageable data domains. Teams can focus on their specific data requirements without being overwhelmed by the entire data schema.

Subgraphs

In Hasura DDN, a subgraph represents a self-contained module of metadata and its accompanying data connector(s) which encapsulates a specific data domain. Subgraphs can be built completely independently of each other and also managed in their own isolated repositories.

Subgraph fields which are exposed to the full supergraph can be prefixed to prevent conflicts in the schema.

Data can be interlinked between subgraphs using relationships and even between subgraphs in separate repositories.

Globals subgraph

When running the ddn supergraph init command, a globals subgraph is created by default for your convenience. This subgraph is intended to hold global configuration objects for the supergraph, such as API configuration and auth settings.

These configuration objects are AuthConfig, CompatibilityConfig and GraphqlConfig as well as the subgraph.yaml configuration file which defines the globals subgraph itself.

These objects are located by default in the globals subgraph, but can be moved to any other subgraph if needed.

Subgraph-level authorization

Authentication is managed at the supergraph level in Hasura DDN as defined by the AuthConfig object and cannot be customized at the subgraph level.

Authorization however, is managed at the subgraph level in Hasura DDN. This means that the permissions for models and commands are defined within the context of those objects in their respective subgraphs, and do not affect other subgraphs.

Authorization rules in one subgraph can also be defined to reference data in a foreign subgraph even if that subgraph is in another repository.

Data connectors

Data Connectors connect subgraphs to data sources. They can communicate to data sources in their native language, and are data source specific so we can leverage all the data source specific functionality.

Each independent subgraph can have one or more data connectors.

Data connectors are available for a variety of data sources, including databases, business logic functions, REST APIs, and GraphQL APIs. You can also create custom data connectors to integrate with other data sources.

The same underlying data source can be connected to multiple subgraphs via data connector instances in each. This allows different teams to work with the same source from the perspective of different data domains.

Read more about data connectors

For a detailed overview of data connectors, check out our Data Connectors Overview page 📚

Relationships

Defining a relationship allows you to make queries across linked information within and between subgraphs.

As always when authoring metadata, the Hasura VS Code extension can assist with auto-complete and validation. When working with relationships across subgraphs in other repositories, there are some differences to be aware of. Find out more about cross-repo relationships here.

Example

Imagine an e-commerce application with separate subgraphs for product catalog management, user profile information, and order processing.

1. Product Catalog Subgraph: A team dedicated to managing product information owns and maintains this subgraph. They use a dedicated PostgreSQL data connector to connect to a relational database containing product details, images, and inventory data.
2. User Profile Subgraph: The User Data team owns this subgraph, using a MongoDB data connector to interact with a document database containing user profiles, preferences, and order history.
3. Order Processing Subgraph: Managed by the fulfillment team, this subgraph utilizes a custom TypeScript connector to handle business logic related to order creation, payment processing, and shipment tracking, integrating with external APIs and services.

Each subgraph is developed, tested, and deployed independently, allowing teams to focus on their specific data domains without interfering with other teams' work. The supergraph combines these subgraphs into a unified API that provides access to all data domains through a single GraphQL endpoint.

Next steps

• Learn more about git workflows when building supergraphs in single-repo or multi-repo setups.
• Learn more about subgraph prefixing to avoid naming collisions in the schema.
• Learn more about cross-repo relationships to link data in subgraphs across