Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

Federated Schemas

Learn about the different types of GraphQL schemas


A federated uses multiple "types" of :

(Composition succeeds)
(Remove routing machinery)
Subgraph
schema
A
Subgraph
schema
B
Subgraph
schema
C
🛠
Composition
Supergraph schema
(A + B + C + routing machinery)
API schema
(A + B + C)

  • Subgraph schemas. Each has a distinct schema that indicates which types and of your composed supergraph it can resolve.
    • These are the only schemas that your teams define manually.
  • Supergraph schema. This schema combines all of the types and fields from your , plus some federation-specific information that tells your which subgraphs can resolve which fields.
    • This schema is the result of performing composition on your collection of subgraph schemas.
  • API schema. This schema is similar to the , but it omits federation-specific types, fields, and that are considered "machinery" and are not part of your public API.
    • This is the schema that your router exposes to clients, which don't need to know internal implementation details about your .

Let's look at an example!

Subgraph schemas

Below are example schemas for three in an e-commerce company's supergraph. Each subgraph is implemented as a separate API:

Users
type Query {
me: User
}
type User @key(fields: "id") {
id: ID!
username: String! @shareable
}
# (Subgraph schemas include
# this to opt in to
# Federation 2 features.)
extend schema
@link(url: "https://specs.apollo.dev/federation/v2.3",
import: ["@key", "@shareable"])
Products
type Query {
topProducts(first: Int = 5): [Product]
}
type Product @key(fields: "upc") {
upc: String!
name: String!
price: Int
}
extend schema
@link(url: "https://specs.apollo.dev/federation/v2.3",
import: ["@key", "@shareable"])
Reviews
type Review {
body: String
author: User @provides(fields: "username")
product: Product
}
type User @key(fields: "id") {
id: ID!
username: String! @external
reviews: [Review]
}
type Product @key(fields: "upc") {
upc: String!
reviews: [Review]
}
# (This subgraph uses additional
# federated directives)
extend schema
@link(url: "https://specs.apollo.dev/federation/v2.3",
import: ["@key", "@shareable", "@provides", "@external"])

As these schemas show, multiple subgraphs can contribute unique fields to a single type. For example, the Products subgraph and the Reviews subgraph both contribute fields to the Product type.

Supergraph schema

The supergraph schema is the output of schema composition. It serves the following purposes:

  • It provides your router with the name and endpoint URL for each of your subgraphs.
  • It includes all types and fields defined by all of your subgraphs.
  • It tells your router which of your subgraphs can resolve which GraphQL fields.

Here's the supergraph schema composed with the subgraph schemas above:

As you can see, the supergraph schema includes a lot of Federation-specific additions! These additions are used only by the router, and you'll never need to add them manually.

API schema

The router uses its supergraph schema to produce an API schema, which it exposes to clients as your actual GraphQL API. This schema cleanly and logically represents the combination of your subgraph schemas:

type Product {
name: String!
price: Int
reviews: [Review]
upc: String!
}
type Query {
me: User
topProducts(first: Int = 5): [Product]
}
type Review {
author: User
body: String
product: Product
}
type User {
id: ID!
reviews: [Review]
username: String!
}

Unlike the supergraph schema, this schema hides the fact that your GraphQL API is composed of multiple distinct GraphQL APIs.

Previous
JetBrains IDE Support
Next
Composition
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy

Company