Federated graphs in Studio

A federated graph (also known as a supergraph ) is a graph that’s composed of multiple individual subgraphs:

Each subgraph represents an underlying service or set of services that provide their own GraphQL API. Different subgraphs are often owned by different teams in an organization.

Apollo Studio provides tools to help multiple teams collaborate on a federated graph and its subgraphs.

Variants and federated graphs

Just like any other deployed graph in Studio, a federated graph can have multiple variants. Each variant has its own subgraph schemas, supergraph schema, change history, and metrics.

In addition, different variants of a federated graph can have completely different sets of subgraphs:

This helps you test out adding new subgraphs (or removing existing ones) in non-production environments.

You specify a subgraph instance's associated variant when you register its schema.

Viewing a field's originating subgraph

The Schema > Reference tab in Studio displays a table of your federated schema’s types and fields. This table includes a Subgraph column:

Clicking the subgraph link for a type or field takes you to the line in the subgraph schema where it's defined:

If you're using the @contact directive to specify owner contact information for your subgraphs, hovering over a subgraph name displays its contact information, enabling you to follow up with the appropriate team:

Viewing subgraph SDL

The Schema > SDL tab in Studio displays the raw SDL of your federated graph’s schema, along with the schema of each subgraph.

From this tab you can:

• View metadata about the composed graph and each subgraph (such as endpoint URL and the most recent schema registration date)
• Identify the originating subgraph for any type or field in your API and share a link with team members
• Search for types and fields
• Download a copy of your subgraph’s SDL for local development
• Filter out comments and deprecated fields for improved scanning

Subgraph contact info

You can use the @contact directive to add your team's contact info to your subgraph schema. This info is displayed in Studio, helping other teams know who to contact for assistance with the subgraph:

The contact info includes a name (of a team or individual), along with an optional description and custom URL.

Adding the @contact directive to your subgraph

To add the @contact directive to your schema, you first need to define the directive. Add the following definition to each of your subgraph schemas:

1
directive @contact(
2
  "Contact title of the subgraph owner"
3
  name: String!
4
  "URL where the subgraph's owner can be reached"
5
  url: String
6
  "Other relevant notes can be included here; supports markdown links"
7
  description: String
8
) on SCHEMA

You can now apply the @contact directive to the special schema object. Many schemas don’t include this object because it’s not required, but you can add it like so:

1
extend schema @contact(
2
  name: "Acephei Server Team",
3
  url: "https://myteam.slack.com/archives/teams-chat-room-url",
4
  description: "send urgent issues to [#oncall](https://yourteam.slack.com/archives/oncall)."
5
)

Supported @contact fields

Known @contact limitations

• To provide the @contact directive to Apollo, you must register your schema by providing a local .graphql file as the --schema option of rover graph publish.

  • If you provide an introspection result to the command instead, directives are not included in the result.

• Similarly, you cannot provide your @contact directive to Apollo via schema reporting. This registration method also does not include directives.

• If your subgraph doesn’t already have a schema object, you need to add one to use the @contact directive. The schema object cannot be empty, so you need to include at least one field in it (most commonly query: Query). If you do provide the Query type like this, it needs to include at least one field in your subgraph’s schema. If your subgraph’s Query type is empty, you need to add a dummy field for the SDL to be valid:

  GraphQL

  schema.graphql

  1
  @contact(...)
  2
  schema {
  3
    query: Query
  4
  }
  5
  
  6
  extend type Query {
  7
    _dummyField: Boolean
  8
  }

  Copy

Viewing contact info

After you register a subgraph schema with the @contact directive, the contact information is included in the metadata shown in Studio’s Schema > SDL tab:

In the Schema > Reference tab, you’ll also see a contact card when you hover over the subgraph link of a type or field:

Schema tagging

In your subgraph schemas, you can use the @tag directive to tag a type or field with an arbitrary string value:

1
type Product {
2
  id: ID!
3
  name: String!
4
  codename: String! @tag(name: "internal")
5
}

By default, these tags are removed from the API schema that's generated as part of composition. This means that tag information isn't visible to clients querying your supergraph.

If tag information should be visible to clients (for example, to help document your API), you can enable this for a variant in Studio with the following steps:

1. Go to the Settings page for your variant in Apollo Studio.
2. On the General tab, click Edit Configuration. The Update Build Configuration dialog appears.
3. If you have a Federation 1 supergraph, enable the toggle for the @tag directive under Directives (this step isn't necessary for Federation 2 supergraphs).
4. Under Build Settings, enable the toggle labeled Show all uses of @tag directives to consumers in Schema Reference and Explorer.
5. Click Save.

After you make your @tag directives visible, you can view them inline with both the Schema and Explorer tabs in Studio.

In the Schema > Reference tab, tags are shown inline with each type and field:

Tags are also visible in the Explorer's Documentation tab:

Federation support in the Explorer

The Apollo Studio Explorer provides enhanced support for working with federated graphs:

• You can preview how your graph resolves data for an operation by inspecting the operation’s query plan in the Response pane.
• While you’re building operations in the Explorer, you can see which subgraph each field of your operation originates in by enabling subgraph hints from the Explorer’s Settings tab.

Viewing composition errors

Studio displays a Federated label next to the name of a federated graph. If a federated graph has composition errors, you can click the label to view the errors that must be resolved before composition can succeed.