securing-a-subgraph Documentation

File: src/content/graphos/basics/config.json Copy Chapter

{
"title": "Graph Essentials",
"algoliaFilters": [
[
"docset:graphos",
"docset:graphos/delivery",
"docset:graphos/metrics",
"docset:graphos/org",
"docset:graphos/explorer",
"docset:graphos/enterprise"
],
[
"docset:rover",
"docset:router",
"docset:federation"
]
],
"sidebar": {
"Intro to GraphOS": "/",
"Graphs and Variants": "/graphs",
"Routing": "/routing",
"Get Started": {
"Cloud Setup": "/quickstart/cloud",
"Self-Hosted Setup": [
"/quickstart/self-hosted",
[
"enterprise"
]
],
"Next Steps": "/quickstart/next-steps"
},
"Graph Development": {
"Creating a New Subgraph": "/graphs/creating-a-subgraph",
"Local Subgraph Development": "/graphs/local-development",
"Updating Your Graph": "/graphs/updating"
},
"GraphOS Studio Features": {
"Graph Exploration": "/graphs/studio-features",
"Supergraph-Specific Features": "/graphs/federated-graphs"
},
"Graph Administration": {
"API Keys": "/api-keys",
"Graph Management": "/graphs/management"
},
"Graph Security": {
"Securing Subgraphs": "/graphs/securing-a-subgraph",
"Safelisting with Persisted Queries": [
"/operations/persisted-queries",
[
"enterprise"
]
]
},
"Client Operations": {
"Using @defer": "/operations/defer",
"GraphQL Subscriptions": [
"/operations/subscriptions",
[
"preview"
]
]
},
"GraphOS Interfaces": {
"Studio UI": "https://studio.apollographql.com",
"Rover CLI": "https://apollographql.com/docs/rover/",
"Platform API": "/platform-api"
},
"Platform Data Processing": {
"Data Privacy / GDPR": "/data-privacy",
"Sub-Processors": "/sub-processors"
}
}
}

File: src/content/graphos/basics/data-privacy.mdx Copy Chapter

title: GraphOS Data Privacy and Compliance Copy Chapter

This article describes which data is and is not sent to Apollo GraphOS by other Apollo tools and libraries.

Our top priority is ensuring the privacy and security of your data and your customers' data. No Apollo tool or library running in your environment sends any data to GraphOS unless you configure it to do so. Features that potentially send highly sensitive data require additional opt-in.

Does GraphOS store operation result data returned by my graph? Copy Chapter

No. Your graph's operation results never even reach any Apollo-managed service, with one important exception: cloud supergraphs use a GraphOS Router, which passes results directly from your subgraphs to requesting clients, without logging, persisting, or sending those results to any other system (other data like operation metrics are persisted).

Which tools send data to GraphOS? Copy Chapter

The GraphOS Router, Apollo Server, the Rover CLI, and the legacy Apollo CLI have opt-in features that send data to GraphOS.

The Rover CLI also collects anonymous usage data by default. You can turn this off.

The Apollo Kotlin IDE plugin also collects anonymous usage data by default. You can turn this off.

If you have a cloud supergraph, its router is hosted and managed by GraphOS, and it automatically enables metrics reporting. Learn about data collection for cloud supergraphs.

Apollo Client libraries do not send data to GraphOS.

Where is data sent? Copy Chapter

All data sent to GraphOS is sent to an endpoint with one of the following base URLs:

Current URLs Copy Section

Active legacy URLs Copy Section

If your environment uses a corporate proxy or firewall, you might need to configure it to allow outbound traffic to these domains. Note that data might be sent to multiple endpoints in a given domain.

Which types of data do the GraphOS Router and Apollo Server send to GraphOS? Copy Chapter

You can configure both the GraphOS Router and Apollo Server to report certain data to GraphOS for each operation resolved by these libraries. These types of data include:

• Several fields besides data from every operation response

  • Neither the GraphOS Router nor Apollo Server ever sends the data field of an operation response to GraphOS.

• The normalized query operation string for every executed operation

• Trace data indicating the execution time for every resolver in the operation

• The values of operation GraphQL variables and HTTP headers

These types of data are covered in the subsections below.

In addition, you can configure a standalone instance of Apollo Server to report its schema to GraphOS.

Operation response fields Copy Section

Let's walk through the default behaviors of the GraphOS Router and Apollo Server when reporting fields in a typical GraphQL response:

// GraphQL Response
{
  "data": { ... },  // NEVER sent to GraphOS
  "errors": [ ... ] // Can be sent to GraphOS, used to report on errors for operations and fields.
}

`response.data`

As mentioned, the GraphOS Router and Apollo Server never send the contents of this field to GraphOS. The responses from your graph stay internal to your application.

`response.errors`

Both the GraphOS Router and Apollo Server can report certain error information to GraphOS, but the exact behavior varies:

The GraphOS Router

Currently, the GraphOS Router reports only which fields in an operation produced errors. Other error details (such as messages) are masked in reports to GraphOS.

You cannot currently configure the GraphOS Router to report any additional error details.

Apollo Server 4

By default, Apollo Server 4 reports only which fields in an operation produced errors.

You can configure Apollo Server 4 to provide additional error details (such as error messages and extensions). To do so, provide the sendErrors option to Apollo Server's usage reporting plugin.

Apollo Server 2 and 3

By default, Apollo Server versions 2 and 3 report all error details to GraphOS, including messages and extensions.

You can use the usage reporting plugin's rewriteError option to filter or transform errors before they're stored in GraphOS. Use this to strip sensitive data from errors or filter "safe" errors from Studio reports.

Query operation strings Copy Section

The GraphOS Router and Apollo Server both report a normalized string representation of each query operation to GraphOS. By default, this normalization algorithm strips out string literals that are passed as arguments. However, we highly recommend that users do not include sensitive data (such as passwords or personally identifiable information) in operation strings. Instead, include this information in GraphQL variables, which you can send selectively.

Operation traces Copy Section

If you're using the GraphOS Router, your subgraphs can include operation trace data in each of their responses to the router. This data includes timing information for each resolver that contributed to the operation.

To check which subgraph libraries support federated traces, consult the FEDERATED TRACING entry in this table.

You can configure the GraphOS Router to include this trace data in its reports to GraphOS (learn how). By doing so, you can visualize the performance of your operations in GraphOS Studio, broken down by resolver.

If you're using a standalone instance of Apollo Server, you can also configure it to report operation traces to GraphOS.

GraphQL variable values Copy Section

This section pertains to the values of variables that are included in GraphQL operations. The names of these variables are included in operation strings that are sent to GraphOS.

Apollo Server 2.7.0 and later

In Apollo Server 2.7.0 and later, none of an operation's GraphQL variable values are sent to GraphOS by default.

You can set a value for the usage reporting plugin's sendVariableValues option to specify a different strategy for reporting some or all variable values.

Apollo Server prior to 2.7.0

In versions of Apollo Server 2 prior to 2.7.0, all of an operation's GraphQL
variable values are sent to GraphOS by default.

If you're using an earlier version of Apollo Server, it's recommended that you update. If you can't update for whatever reason, you can use the privateVariables reporting option to specify the names of variables that should not be sent to GraphOS. You can also set this option to false to prevent all variables from being sent. This reporting option is deprecated and will not be available in future versions of Apollo Server.

GraphOS Router

By default, the GraphOS Router does not send an operation's GraphQL variable values to GraphOS.

To enable variable value reporting in the GraphOS Router, see this section.

HTTP headers Copy Section

Regardless of your server configuration, GraphOS never collects the values
of the following HTTP headers, even if they're sent:

• Authorization
• Cookie
• Set-Cookie

You can, however, configure reporting options for all other HTTP headers.

Apollo Server 2.7.0 and later

In Apollo Server 2.7.0 and later, none of an operation's HTTP headers is sent to GraphOS by default.

You can set a value for the usage reporting plugin's sendHeaders option to specify a different strategy for reporting some or all your HTTP headers.

Apollo Server prior to 2.7.0

In versions of Apollo Server 2 prior to 2.7.0, all of an operation's HTTP headers (except the confidential headers listed above) are sent to GraphOS by default.

If you're using an earlier version of Apollo Server, it's recommended that you
update. If you can't update for whatever reason, you can use the privateHeaders reporting option to specify the names of variables that should not be sent to GraphOS. You can also set this option to false to prevent all headers from being sent. This reporting option is deprecated and will not be available in future versions of Apollo Server.

GraphOS Router

By default, the GraphOS Router does not send an operation's HTTP header values to GraphOS.

To enable header reporting in the GraphOS Router, see this section.

Which types of data are collected by a cloud supergraph? Copy Chapter

A cloud supergraph uses a GraphOS Router to execute operations across one or more subgraphs hosted in your infrastructure:

flowchart LR;
  clients(Clients);
  subgraph "GraphOS";
  router(["Router"]);
  end;
  subgraph "Your infrastructure";
  subgraphA[Subgraph A];
  subgraphB[Subgraph B]
  router --- subgraphA
  router --- subgraphB
  end;
  clients -.- router;
  class clients secondary;

Each instance of GraphOS Router runs in its own managed container. These instances use the same mechanisms to report operation metrics to GraphOS as a GraphOS Router or Apollo Router Core instance running in any other environment. The only difference is that metrics reporting is always enabled for a cloud supergraph's router.

GraphOS Routers do not persist or log any response data returned by your subgraphs. They only assemble this data into responses for requesting clients.

What data does GraphOS log about operations executed in the Explorer? Copy Chapter

Only frontend usage metrics for improving the product. The GraphOS Studio Explorer enables you to build and execute operations against your graph. These operations are sent directly from your browser and do not pass through Apollo systems.

GDPR Copy Chapter

Effective May 25, 2018, the General Data Protection Regulation (GDPR) expands European Union (EU) residents' (Data Subjects) rights concerning their personal data. Meteor Development Group Inc. (“MDG” also dba Apollo) stands ready to assist our customers to become or remain compliant with GDPR after this crucial transition.

What is GDPR?

GDPR standardizes EU regulations and expands the rights of Data Subjects pertaining to personal data while expanding the definition of what constitutes personal data. GDPR provides Data Subjects with increased rights to control and delete their personal data, and it broadly prohibits the processing of special categories of personal data.

How has Apollo prepared for GDPR?

We have been complying with GDPR since before it became enforceable on May 25, 2018. We are enhancing our products, processes, and procedures to meet our obligations as a data processor (Processor).

How will GDPR affect the way companies use Apollo's products or services?

Our products and services are not intended to be used for processing personal data. Our products and services are focused on software, systems, and applications - not individuals. If a customer wishes to set up a custom API, custom attribute, or custom event to track such data, it may do so. Our processing is data agnostic and automated, so all data is processed in the same way in accordance with a customer's configuration. If, however, a customer believes that it has included personal data in the information processed by Apollo, we will assist the customer in meeting its obligations in accordance with the requirements of GDPR and the terms of our Data Processing Agreement.

How can Apollo assist customers in meeting their obligations under GDPR?

As a Processor, we will assist customers in fulfilling their obligations as data controllers (Controllers) by:

• supporting customers in complying with requests from Data Subjects
• aggregating applicable personal data for customers replying to complaints from Data Subjects
• replying to investigations and inquiries from supervisory authorities concerning processing activities on behalf of a customer
• conducting Data Protection Impact Assessments

How can Apollo help address requests from Data Subjects?

Apollo has implemented a process to intake, review, and fulfill customer requests arising from Data Subject Access Requests (DSAR) they receive. As a result of a DSAR, customers might request that Apollo securely delete or return the Data Subject's personal data. Due to their sensitivity, such requests will be handled by Apollo on a case-by-case basis.

Where can I learn more about Apollo's security and privacy policies?

The legal terms and policies that apply to Apollo's corporate websites and customer products or services are available at https://www.apollographql.com/Apollo-Website-Terms-of-Service.pdf and https://www.apollographql.com/Apollo-Terms-of-Service.pdf.

Where can I get more help?

If you have any additional questions or encounter any issues, please reach out to support.

Organizations with an Enterprise plan can request a Data Processing Addendum (DPA) from support.

Requesting deletion of data Copy Chapter

To request the deletion of specific data from your Apollo organization, please email [email protected] with the subject Data deletion request.

In your email, please include the following:

• A description of the data that needs to be deleted
• An approximate timestamp of when that data was reported to Apollo
• The ID of the graph that the data is associated with

You can also request that members of your organization be removed from marketing outreach. To do so, provide the email addresses of those members in your email.

Policies and agreements Copy Chapter

To learn about other ways that we protect your data, please read over our Terms of Service and Privacy Policy.

File: src/content/graphos/basics/index.mdx Copy Chapter

title: Introduction to Apollo GraphOS subtitle: The GraphQL developer platform Copy Chapter

Apollo GraphOS is the platform for building, managing, and scaling a supergraph: a network of your microservices and their data sources—all composed into a unified GraphQL API.

flowchart LR;
  clients("GraphQL<br/>Clients");
  subgraph "<b>Apollo GraphOS</b>";
  registry(["Schema<br/>Registry"]);
  router(["Graph<br/>Router"]);
  studio(["Studio UI"]);
  end;
  subgraph "Your infrastructure";
  products["GraphQL API<br/>A"];
  reviews["GraphQL API<br/>B"];
  router -->|Sub-query| products & reviews
  dbA[( )];
  dbB[( )];
  products --- dbA;
  reviews --- dbB;
  end;
  clients -.->|Query| router;
  class clients secondary;

Create your first supergraph!


What's a supergraph?

What's in GraphOS? Copy Chapter

The GraphOS platform provides an ever-growing collection of tools and services to help you build your supergraph and scale it safely.

Core features Copy Section

These features (along with many others) are available to organizations on Apollo Serverless and Dedicated plans:

• Cloud routing
  • GraphOS automatically provisions and hosts a router for each of your supergraphs. Clients query your router instead of individual subgraphs, enabling the router to automatically collect operation metrics that you can then visualize in GraphOS Studio.
• The schema registry
  • GraphOS tracks the GraphQL schemas for all your individual subgraphs, and it also handles composing those subgraph schemas into one supergraph schema for your router.
• Safe schema delivery
  • The schema checks feature of GraphOS enables you to verify whether proposed changes to a subgraph will cause an issue with other subgraphs, or with any of your existing clients.
  • Whenever you update a subgraph schema, GraphOS composes a new supergraph schema for your router. If composition succeeds, your router automatically begins using its new schema.
  • You can view the results of each launch that takes place whenever you update a subgraph schema, helping you resolve any issues that might occur.
• An interface for every use case
  • GraphOS Studio is the primary web interface for GraphOS. Among other capabilities, you use Studio to create your organization and its supergraphs, view schemas and metrics, and test out operations in the Explorer.
  • The Rover CLI is the primary command-line interface for GraphOS. Among other capabilities, you use Rover to publish subgraph schemas to the registry, run schema checks from CI, and test out your supergraph within your development environment.
  • If you want to automate your own workflows outside of Studio or Rover, you can use the official GraphOS Platform API to do so. We'll expose more GraphOS capabilities through the Platform API over time.

Enterprise features Copy Section

Additional GraphOS features are available to organizations on an Enterprise plan:

• Connect your self-hosted router to GraphOS
  • The Apollo Router Core is available as a free and source-available runtime for Apollo Federation. Connecting your self-hosted router to GraphOS requires an Enterprise plan. Once you connect the Apollo Router Core to GraphOS, it is called GraphOS Router.
  • Deploy GraphOS Routers inside your own infrastructure, enabling you to maximize performance and fully customize their behavior. Self-hosted routers use the same powerful technology that cloud routing uses under the hood.
  • Enable advanced features for your router fleet, such as operation limits and Redis-backed distributed caching.
• Supergraph filtering with contracts
  • Deploy multiple instances of your router that each use a different filtered subset of your supergraph's schema. Different clients can then communicate with different routers, limiting them to whichever parts of your supergraph they should have access to.
• Enhanced user management
  • Assign fine-grained user roles to organization members, and optionally override those roles on a graph-by-graph basis.
  • Set up single sign-on (SSO) with your identity provider.
  • Export audit logs of all material events that occurred within your organization over a time period.
• Extended data retention
  • Your supergraph's historical operation metrics are available for visualization in Studio longer than with other plans. See the pricing page's section on data retention for details.

An Enterprise plan also provides access to our Graph Champions community and a dedicated support channel for your team to connect with Apollo supergraph experts. We'll work with you to customize a query volume limit and support package that's right for you.

If you're interested in Enterprise features, please get in touch with us! You can also test out these features with a free Enterprise trial.

Ready to create your first supergraph?

Get started with GraphOS!

File: src/content/graphos/basics/platform-api.mdx Copy Chapter

title: The GraphOS Platform API subtitle: Automate GraphOS tasks in your own code Copy Chapter

The GraphOS Platform API enables you to perform GraphOS actions from your own custom application. Currently, these actions include:

• Fetching details about your organization's graphs
• Publishing schemas to new or existing variants
• Running schema checks and obtaining their results
• Creating and editing schema proposals, including adding reviewers
• Removing variants from a graph
• Removing subgraphs from a supergraph
• Managing API keys

We'll continue to expand the Platform API with additional GraphOS functionality over time.

API docs Copy Chapter

The Platform API is itself represented as a public graph in GraphOS! Documentation for the API (which includes a README and collections of example operations) is available in GraphOS Studio.

Open Platform API docs

File: src/content/graphos/basics/routing.mdx Copy Chapter

title: Routing for Supergraphs subtitle: Learn about self-hosted and cloud routing options Copy Chapter

With supergraph architecture (also known as Apollo Federation), each component service is known as a subgraph. A router acts as an entry point to your subgraphs and provides a unified interface for clients to interact with. Clients send operations to your router's public endpoint instead of directly to your APIs.

flowchart LR;
  clients(Clients);
  router(["Router"]);
  subgraphA[Subgraph A];
  subgraphB[Subgraph B];
  router --- subgraphA & subgraphB;
  clients -.- router;
  class clients secondary;

The router intelligently executes each incoming client operation across the appropriate combination of subgraphs. It then merges subgraph responses into a single response for the client. You can configure your router's error handling, CORS settings, other security features, and more. Your configuration options depend on your router type.

Router types Copy Chapter

GraphOS comes with a fully integrated router called the GraphOS Router.
You can choose for Apollo to provision and manage a cloud-hosted GraphOS Router for you:

flowchart LR;
  clients(Clients);
  subgraph "GraphOS Cloud"
    router(["GraphOS Router"]);
  end;
  subgraph YourInfra["Your infrastructure"];
    subgraphA[Subgraph A];
    subgraphB[Subgraph B];
  end;
  clients -.- router;
  router --- subgraphA & subgraphB;
  classDef padding padding-left:1em, padding-right:1em
  YourInfra:::padding
  class clients secondary;

Or you can choose to self-host your GraphOS Router:

flowchart LR;
  clients(Clients);
  subgraph "Your infrastructure";
  router(["GraphOS Router"]);
  serviceB[Subgraph A];
  serviceC[Subgraph B];
  router --- serviceB & serviceC;
  end;
  clients -.- router;
  class clients secondary;

Both cloud and self-hosted GraphOS Routers are based on the Apollo Router Core—a high-performance routing runtime packaged as a standalone binary.

Router comparison Copy Section

GraphOS offers the following router options, in increasing order of configurability:

subgraph error inclusion | [Serverless](https://apollographql.com/pricing) |

| Dedicated cloud router | Apollo provisions and manages routers on dedicated infrastructure that
you control and scale. | Highly configurable, including all options for shared cloud routers and
additional configurations | Dedicated |
| Self-hosted router | You host and manage the router on your own infrastructure. | Highly configurable and customizable, including all options for Cloud
Dedicated routers and additional{' '}
customization options | The Apollo Core Router is available as a free and source-available
runtime. Connecting a self-hosted router to GraphOS requires an{' '}
Enterprise plan. |

GraphOS Router features Copy Section

Although all GraphOS Routers (both cloud- and self-hosted) are based on the source-available Apollo Router Core binary, they offer an expanded feature set that isn't available when running the Apollo Router Core without connecting it to GraphOS.

Cloud-hosted routers automatically have access to GraphOS Router features, while self-hosted routers must be authenticated with a GraphOS Enterprise license to gain access to these features. Refer to the pricing page to compare GraphOS Router features across plan types.

Setup and configuration Copy Chapter

For setup and configuration instructions, refer to the respective router documentation:

• Cloud router on shared infrastructure
• Cloud router on dedicated infrastructure
• Self-hosted router

File: src/content/graphos/basics/sub-processors.mdx Copy Chapter

title: Sub-Processors Copy Chapter

Apollo Graph, Inc. ("Apollo") may use third-party data processors ("Sub-processors") to process Customer Personal Data as defined in the Apollo Customer Data Processing Addendum, or other personal data which you as customer are permitted to submit to Apollo for processing per our mutual written agreement ("Customer Personal Data"). Capitalized terms not defined on this page have the meanings given to them in the written agreement between you and Apollo (the "Agreement").

By subscribing to receive updates about this page, you will be notified by email about changes to Apollo's Sub-processors that may be involved in processing your Customer Personal Data.

How to subscribe to updates Copy Chapter

Current Apollo customers must subscribe to receive email notification of updates to Sub-processors and by submitting (1) the email address for such notifications and (2) the full name of the legal entity that has signed the Agreement with Apollo. By submitting this information, you represent that you are an Apollo customer and have all necessary rights to provide this information to Apollo.

How to object to a new Sub-processor Copy Chapter

If you are a current Apollo customer, with a fully executed data processing agreement ("DPA") in place with Apollo, you may notify Apollo of an objection to its use of a new Sub-processor used to process Customer Personal Data by sending such objection to [email protected] within fourteen days after Apollo's notice of such new Sub-processor, or such other period of time as set forth in your DPA. Objections will be handled as described in the DPA.

File: src/content/graphos/basics/graphs/creating-a-subgraph.mdx Copy Chapter

title: Creating a New Subgraph subtitle: Add a subgraph to your supergraph using a template or existing API Copy Chapter

This article helps you get started building a new subgraph that you can then add to your GraphOS supergraph.

• If you're building a new GraphQL API from scratch, we recommend starting from a template!
• If you already have a GraphQL API to use as a subgraph, see Starting with an existing API.

Starting from a template Copy Chapter

The fastest way to create a new subgraph is to start with one of the templates provided by the Rover CLI. The rover template command generates the skeleton of a new subgraph for you, so you can immediately begin defining your schema and implementing your resolvers.

You start by running rover template use, providing it the ID of your chosen template. For example, the following command creates a new directory called my-subgraph that contains the boilerplate code for a subgraph written in TypeScript using the Apollo Server library:

rover template use "my-subgraph" --template="subgraph-typescript-apollo-server"

After generating the boilerplate code, you can start filling in your business logic. The generated code includes example resolvers for Query and Mutation, along with some entity types to use as your starting point. All templates also come with example GitHub Actions workflows to help with publishing your schema in CI/CD.

When you're ready to add your new subgraph to your supergraph, see below.

Starting with an existing API Copy Chapter

If you have an existing GraphQL API that you want to use as a subgraph, confirm whether it uses a subgraph-compatible library.

• If it does, consult the library's documentation to determine how to enable its support for Apollo Federation.
• If it doesn't, open an issue to let us know and we'll work with the library's maintainers to add support.

Adding to your supergraph Copy Chapter

When you're ready to add a new subgraph to your existing GraphOS supergraph, do the following:

1. Enable federation support in your subgraph library.
   • If you built from a template, federation support is already enabled. Otherwise, consult the documentation for your chosen library.
2. Check your schema against your existing supergraph and handle any conflicts.
3. Set up your CI/CD pipeline to perform checks and also publish your subgraph schema.

After you publish your subgraph's schema for the first time, GraphOS recognizes it as part of your supergraph, and you can start querying for data from all your subgraphs!

File: src/content/graphos/basics/graphs/federated-graphs.mdx Copy Chapter

title: Supergraph-Specific Features subtitle: Learn about variants, managing subgraphs, and viewing compositions errors Copy Chapter

GraphOS Studio provides tools to help multiple teams collaborate on a supergraph and its subgraphs.

Supergraph variants Copy Chapter

Each variant of a Studio supergraph has its own subgraph schemas, supergraph schema, change history, and metrics.

Different variants of a supergraph can even have completely different sets of subgraphs:

graph BT;
  subgraph "Staging"
  router2(["Router"]);
  users2[Users];
  products2[Products];
  reviews2[Reviews];
  router2 --- users2 & products2 & reviews2;
  end

  subgraph "Production"
  router(["Router"]);
  users[Users];
  products[Products];
  router --- users & products;
  end

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

When you publish a subgraph's schema, you can specify which variant of the supergraph you're publishing that schema to.

Adding a variant Copy Section

You can add a new variant to your existing GraphOS supergraph in the following ways:

• In GraphOS Studio (cloud supergraphs only)
• Via the Rover CLI

Adding a variant in GraphOS Studio

1. Go to your supergraph's Settings page in Studio and navigate to This Graph > Variants.

2. Click Add a variant.

3. In the dialog that appears, provide a Variant Name and click Continue.

4. Provide your first subgraph's Routing URL (this is the URL that your new variant's router will use to communicate with the subgraph), along with a Subgraph Name.

   • Creating a new supergraph variant always requires also creating the first subgraph for that variant.

5. If Studio can't fetch your subgraph's schema automatically from the routing URL, click Advanced options to provide the schema another way (such as by pasting the schema directly or introspecting a locally running server).

6. Click Add a new variant. When the action completes, your new variant is listed on your organization's homepage in Studio.

Adding a variant via the Rover CLI

To add a new variant to your supergraph with Rover, you publish its first subgraph's schema! To do this, you use the exact same Rover command as updating an existing subgraph. The only difference is that you provide the name of the new variant to the command.

Learn about publishing subgraph schemas.

Managing subgraphs Copy Chapter

After you create a cloud supergraph (or a new variant of one), you can view a list of its associated subgraphs from the variant's Subgraphs page:

The list includes each subgraph's name and routing URL, along with type and field counts for each subgraph's schema.

Adding a new subgraph Copy Section

You can add your new subgraph to your GraphOS supergraph in the following ways:

• In GraphOS Studio (cloud supergraphs only)
• Via the Rover CLI

Adding a subgraph in GraphOS Studio

1. Go to your variant's Subgraphs page in Studio.

2. Click Add a subgraph.

3. In the dialog that appears, provide your subgraph's Routing URL (this is the URL that your supergraph's router will use to communicate with the subgraph), along with a Subgraph Name.

4. If Studio can't fetch your subgraph's schema automatically from the routing URL, click Advanced options to provide the schema another way (such as by pasting the schema directly or introspecting a locally running server).

5. Click Add Subgraph. When the action completes, your new subgraph is listed on the Subgraphs page.

Adding a subgraph via the Rover CLI

To add a subgraph to your supergraph with Rover, you publish the subgraph's schema! To do this, you use the exact same Rover command as updating an existing subgraph. The only difference is that you provide the name of the new subgraph to the command.

Learn about publishing subgraph schemas.

Modifying a subgraph Copy Section

From your variant's Subgraphs page, you can modify an existing subgraph's routing URL:

1. Open the ••• menu for the subgraph you want to modify:

2. Click Edit routing URL.

3. In the dialog that appears, provide a new URL and click Update.

   • Your router automatically begins using the new URL to communicate with your subgraph.

If you need to make any other modifications to an existing subgraph, use the Rover CLI. Learn about rover subgraph commands.

Deleting a subgraph Copy Section

You can delete an existing subgraph from a variant of your cloud supergraph. If you do:

1. The variant automatically attempts to compose an updated supergraph schema using the schemas from all remaining subgraphs.

   • Studio displays the result of this attempt, and you can cancel the deletion if there are errors.

2. If composition succeeds, the variant's router automatically begins using the updated supergraph schema. This means clients can no longer query the router for fields that are defined only in the deleted subgraph.

   If composition fails, the router continues using its existing supergraph schema. This means clients can continue querying the router for fields from the deleted subgraph, until the remaining subgraph schemas are updated to compose successfully.

⚠️ Important considerations

• Deleting a subgraph can break existing clients! This action is equivalent to removing all the subgraph's types and fields from your supergraph (unless they're also defined in another subgraph). If a client sends an operation that includes any of those types and fields, the router will reject that operation.

  • To help you remove schema definitions safely, learn about schema checks.

• Deleting a subgraph in Studio has no effect on your actual running subgraph instance. It only removes your router's knowledge of that instance and its corresponding schema fields.

Steps to delete within Studio

1. Go to the Subgraphs page for the subgraph's corresponding variant.

2. Click the ••• button on the right of the subgraph you want to delete:

3. Click Delete subgraph. Studio attempts to compose a new supergraph schema that doesn't include the subgraph you want to delete.

4. A confirmation dialog appears that displays any composition errors that occurred. If you're sure you want to delete the subgraph, enter its name and click Delete subgraph.

Viewing a field's originating subgraph Copy Chapter

The Schema > Reference page in Studio displays a table of your supergraph's types and fields. This table includes a Subgraph column, which lists the subgraphs that define each type and field:

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

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 Copy Chapter

The Schema > SDL page in Studio displays the raw SDL for each schema type associated with your supergraph—an API schema, a supergraph schema, and subgraph schemas.

From this page, you can:

• View metadata about the composed supergraph, along with metadata about each subgraph (such its endpoint URL and most recent schema registration date)
• Identify which subgraphs define 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

Contact info for subgraphs Copy Chapter

You can use the @contact directive to add your team's contact info to a subgraph schema. This info is displayed in Studio, which helps 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 Copy Section

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

"Annotate a schema with contact information for the subgraph owner"
directive @contact(
  "Contact title of the subgraph owner"
  name: String!
  "URL where the subgraph's owner can be reached"
  url: String
  "Other relevant notes can be included here; supports markdown links"
  description: String
) on SCHEMA

You can now apply the @contact directive to each subgraph schema's special schema object. If your schema doesn't already define this object, you can add it like so:

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

Supported `@contact` fields

String! | Required. The name of the person, people, or team responsible for the subgraph. |
| ##### url

String | The URL where the subgraph's owner can be reached. This might be the URL of a chat room or forum, or it could be an email address. |
| ##### description

String | Provides any additional helpful details about working with this subgraph or contacting its owner.

This field supports Markdown-formatted links. |

Known `@contact` limitations

• To provide the @contact directive to Apollo, you must publish your subgraph schemas by providing a local .graphql file as the --schema option of rover subgraph publish.
  • If you provide an introspection result to the command instead, the @contact directive is not included in that result.

Viewing contact info Copy Section

After you publish a subgraph schema that includes 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 Copy Chapter

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

type Product {
  id: ID!
  name: String!
  codename: String! @tag(name: "internal")
}

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 GraphOS 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:

Supergraph support in the Explorer Copy Chapter

The GraphOS Studio Explorer provides enhanced support for working with supergraphs:

• You can preview how your supergraph's router 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 Copy Chapter

If a supergraph's most recent set of subgraph schemas failed to compose, a BUILD FAILED label is shown at the top of the supergraph's page in Studio. You can click this label to view the errors that must be resolved before composition can succeed. Refer to the composition error reference for more information.

File: src/content/graphos/basics/graphs/index.mdx Copy Chapter

title: Understanding Graphs subtitle: Learn about graph types, variants, and how to publish schemas Copy Chapter

GraphOS is a platform for building and managing graphs. Each graph corresponds to a GraphQL service in your organization.

A GraphQL service usually runs in more than one environment—for example, staging or production—so every graph in GraphOS has one or more variants that each correspond to one environment:

graph LR;
  subgraph "A graph in GraphOS";
    direction TB
    staging(Staging<br/>variant);
    production(Production<br/>variant);
  end;

Each variant of a graph keeps track of its own separate GraphQL schemas and operation metrics.

Graph types Copy Chapter

Every graph in GraphOS is one of these graph types:

• A GraphOS Router
• One or more subgraphs hosted in your infrastructure

Recommended for all organizations getting started with GraphOS. |
| Self-hosted supergraph

(Enterprise only) | A supergraph consisting of:

• A GraphOS Router hosted in your infrastructure
• One or more subgraphs hosted in your infrastructure

Recommended for enterprise organizations that require full customization of their router, usually for advanced performance or data compliance reasons. |
| Monograph

(Enterprise only) | A single GraphQL service hosted in your infrastructure with no router.

⚠️ Not recommended. |

Cloud supergraphs Copy Section

Cloud supergraphs are recommended for every organization that's getting started with GraphOS. For every variant of a cloud supergraph, GraphOS provisions and manages a router that acts as the variant's public endpoint. Application clients communicate with this endpoint instead of communicating directly with your GraphQL server(s):

flowchart LR;
  clients(Clients);
  subgraph "GraphOS Cloud";
  router(["GraphOS Router"]);
  end;
  subgraph "Your infrastructure";
  api["Your GraphQL<br/>server"];
  router --- api
  end;
  clients -.- router;
  class clients secondary;

The router automatically reports certain operation metrics to GraphOS, so you don't need to configure this reporting in your GraphQL servers.

Cloud supergraphs use an architecture called Apollo Federation. With federation, you can distribute your supergraph's capabilities across multiple GraphQL services, which are known as subgraphs. The router executes client operations across multiple subgraphs as needed:

flowchart LR;
  clients(Clients);
  subgraph "GraphOS Cloud";
  router(["GraphOS Router"]);
  end;
  subgraph "Your infrastructure";
  products[Products subgraph];
  reviews[Reviews subgraph]
  router --- products & reviews
  end;
  clients -.- router;
  class clients secondary;

Even if your API currently uses only one GraphQL server, a cloud supergraph helps you add more subgraphs later as your organization grows.

Get started with a cloud supergraph

Self-hosted supergraphs Copy Section

With a self-hosted supergraph, GraphOS does not provision a router for your supergraph. Instead, you host your supergraph's router in your own infrastructure:

flowchart LR;
  clients(Clients);
  subgraph "Your infrastructure"
  router(["GraphOS Router"]);
  serviceA[Products subgraph];
  serviceB[Reviews subgraph];
  router --- serviceA & serviceB;
  end;
  clients -.- router;
  class clients secondary;

Self-hosted supergraphs provide full control over your router, but they also require handling its deployment and management. Before you adopt this graph type, make sure you have the necessary team structure to properly manage an additional service in your infrastructure.

Get started with a self-hosted supergraph

Monographs Copy Section

A monograph is a graph that consists of a single GraphQL server with no router:

flowchart LR;
  clients(Clients);
  subgraph "Your infrastructure"
  server[GraphQL server];
  end;
  clients -.- server;
  class clients secondary;

Creating graphs Copy Chapter

You can create a cloud supergraph or a non-cloud supergraph (self-hosted or monograph).

<Tabs labels={['Cloud','Non-cloud']}>

Next, you need to publish your graph's schema(s) to Apollo using the Rover CLI. For details, see Publishing schemas to GraphOS.

Variants Copy Chapter

To distinguish between instances of the same graph running in different environments (such as staging and production), you define multiple variants of your graph. Each variant has its own schemas, along with its own change history and metrics.

Each of your graph's variants is shown in GraphOS Studio:

Creating a variant Copy Section

See this section.

Publishing schemas Copy Chapter

See Publishing schemas to GraphOS.

File: src/content/graphos/basics/graphs/local-development.mdx Copy Chapter

title: Local Subgraph Development subtitle: Use the Rover CLI to run a local supergraph Copy Chapter

While you're working on changes to one of your subgraphs, you can run a version of your entire supergraph locally in your development environment. To do this, you use the rover dev command.

The rover dev command monitors each of your subgraph schemas (either via server introspection or by watching a .graphql file). Whenever it detects a change, it automatically recomposes your router's supergraph schema and raises any errors that might occur. This enables you iterate quickly on schema changes.

Starting your router Copy Chapter

You run rover dev once for each subgraph in your supergraph. The first time you run it, Rover spins up a router on your local machine.

Try running rover dev with an example subgraph like so:

rover dev --url https://flyby-locations-sub.herokuapp.com/ --name locations

You'll see output like the following:

WARN: could not detect a schema in the current working directory. to watch a schema, pass the `--schema <PATH>` argument
👂 polling https://flyby-locations-sub.herokuapp.com/ every 1 second
⚠️  Do not run this command in production! ⚠️  It is intended for local development.
🛫 starting a session with the 'locations' subgraph
🎶 composing supergraph with Federation v2.1.2
🚀 your supergraph is running! head to http://localhost:3000 to query your supergraph

You can now open http://localhost:3000 in your browser and run test queries against your local router using the Explorer!

You can replace the example subgraph URL and name in the above command with the details for your own subgraph. You can provide a remote URL or a localhost URL.

Adding a subgraph Copy Chapter

To add a subgraph to your local supergraph, run rover dev again in a separate terminal window.

You can add a subgraph to this article's example supergraph with the following command:

rover dev --url https://flyby-reviews-sub.herokuapp.com/ --name reviews

This command's output is similar to the output for the initial execution, but it includes a line like the following:

🐤 adding the 'reviews' subgraph to the session

This indicates that rover dev has identified your existing supergraph session and is adding this subgraph to it.

Now if you run test queries in the Explorer, you'll see that they can include fields from both the locations and reviews subgraphs!

Ending a `rover dev` session Copy Chapter

To shut down your local supergraph, use CTRL+C to stop the first rover dev process you started. This automatically terminates all secondary rover dev processes that are part of the same session.

Command options Copy Chapter

For more details on rover dev options, see the Rover documentation.

File: src/content/graphos/basics/graphs/management.mdx Copy Chapter

title: Graph Management in GraphOS subtitle: Manage access permissions and transfer and delete graphs Copy Chapter

Creating graphs Copy Chapter

• To create a cloud supergraph, see the GraphOS quickstart.
• To create a non-cloud graph (a self-hosted supergraph or a monograph), see this section.

Managing access permissions Copy Chapter

Public variants Copy Section

You can enable public access for individual variants of your graph. If you do, anyone with that variant's public link can view the following pages for that variant in Studio:

• Home
  • This shows the variant's README.
• Schema
• Explorer
  • You can also embed the Explorer on your own webpage.

This enables consumers of your graph to learn about your graph's schema and any special usage information (such as authentication details) that you've documented in the public variant's README. They can also run properly authenticated operations against your graph with the Explorer.

People outside your organization can't view any other pages for a public variant (Fields, Operations, etc.), and they can never view any pages for private variants. New variants always start as private.

Making a variant public

1. Go to your variant's Settings page and open the This Variant tab.
2. Under Danger Zone, find the Public card and click Change.
3. Toggle your selection and click Save.

You can toggle the switch back to Off to make the variant private again.

After you make a variant public, you can click the variant's PUBLIC label at the top of GraphOS Studio to get its public link:

Protected variants (Enterprise only) Copy Section

If you have a GraphOS Enterprise plan, you can designate particular variants of a graph as protected variants. A protected variant limits the capabilities of users with the Contributor role to make certain changes to the variant:

• Contributors cannot push schema updates to a protected variant.
• Contributors cannot manage Explorer-related settings for a protected variant, such as setting the variant's endpoint URL.
• Graph API Keys with the Contributor role cannot report usage metrics for a protected variant.

Graph Admins and Org Admins can configure whether a variant is protected from the This Variant tab of the variant's Settings page.

Internal graph visibility (Enterprise only) Copy Section

By default, graphs are visible to all members of your organization. If you have a GraphOS Enterprise plan, you can set a graph to instead be visible only to members you invite.

You can configure visibility and grant your organization's members explicit access to your graph from the Permissions tab of your graph's Settings page.

Dangerous actions Copy Chapter

Transferring graph ownership Copy Section

You can transfer a graph to a different GraphOS organization you belong to
by visiting the graph's Settings page in Studio and changing the graph owner.

Deleting a graph Copy Section

You can delete a graph from Studio by visiting its Settings page and clicking
Delete Graph.

File: src/content/graphos/basics/graphs/securing-a-subgraph.mdx Copy Chapter

title: Securing Subgraphs subtitle: Restrict access to your cloud supergraph using secrets Copy Chapter

To keep your supergraph secure, it's important that your individual subgraphs are queried only by your router. That's because your subgraphs expose powerful fields that the router uses to execute operations across them. External clients should not have access to these fields.

This article describes steps for securing your subgraphs when using a cloud supergraph.

Step 1. Generate a shared secret Copy Chapter

To restrict subgraph communication to only your router, we recommend creating a separate shared secret for each of your subgraphs. Whenever your router queries a subgraph, it includes that subgraph's corresponding secret in an HTTP header.

You can generate a random secret using a variety of tools. For example, most password managers provide this functionality.

Here are some shell commands that generate a suitably random secret if you have the corresponding tool installed:

• openssl rand -base64 256
• python -c "import secrets; print(secrets.token_urlsafe(256))"
• node -e "console.log(require('crypto').randomBytes(256).toString('base64'));"

Step 2. Add the secret to your router config Copy Chapter

Your cloud supergraph's router needs to know the shared secret so it can include it in all requests to the corresponding subgraph. You add the secret in the Cloud Routing section of your graph variant's Settings page.

After you define the secret, you can inject its value into your router's configuration as an environment variable, as shown below. We recommend setting the value in a header named Router-Authorization (and again, create a separate secret for each subgraph):

headers:
  subgraphs:
    products:
      request:
        - insert:
            name: 'Router-Authorization'
            value: '${env.PRODUCTS_SUBGRAPH_SECRET}'
    users:
      request:
        - insert:
            name: 'Router-Authorization'
            value: '${env.USERS_SUBGRAPH_SECRET}'

Step 3. Configure the subgraph to require the secret Copy Chapter

The exact steps you take to require the shared secret in your subgraph depend on:

• The language and framework your subgraph uses
• The service you use to host your subgraph

Most cloud providers include a mechanism for saving secrets that are then made available to your application as environment variables. Your subgraph should read the secret from an environment variable and reject any incoming requests that don't include that secret in the specified header.

Step 4. Test the configuration Copy Chapter

After adding the shared secret to both your router and subgraph, do the following to confirm that communication has been secured as intended:

1. Verify that your router can still communicate with the subgraph by executing a test query against the router from the Explorer.
   • Make sure the query includes at least one field from the relevant subgraph!
2. Verify that other clients can't communicate with the subgraph by executing a test query against the subgraph directly.
   • This query should fail with an authorization error.

File: src/content/graphos/basics/graphs/studio-features.mdx Copy Chapter

title: Graph Exploration subtitle: Explore and visualize your graph's types, fields, and relationships Copy Chapter

As your graph grows, understanding its structure can become more difficult.
Without understanding a schema's intricacies—particularly how subgraphs relate to one another—development can become blocked or take wrong turns.

GraphOS Studio features Copy Chapter

GraphOS Studio provides several ways of understanding and exploring your organization's graphs, including:

• An editable Overview page that describes the graph to newcomers
• The Schema page, which includes three distinct views, including schema visualization
• The Explorer, which helps you build new operations against your graph
• The Changelog, which displays all published changes

Viewing graph pages Copy Chapter

After selecting an organization in GraphOS Studio, click a particular graph variant to view its pages.

Page permissions Copy Section

With Serverless and Dedicated plans, all Studio organization members have access to all pages, including Settings for all graphs within the organization. Enterprise accounts can set member roles to configure fine-grained access for individual members of their organization.

The Overview page Copy Chapter

When a user opens one of your graph's variants in GraphOS Studio, its Overview page appears. Like a typical homepage for a Git repository, this page displays a Markdown-based README that you can edit with any content you like.

Each variant has its own README. If you edit one variant's README, those edits aren't applied to other variants. Among other uses, this enables you to provide different information to external consumers in a public variant.

Supported Markdown Copy Section

The README supports all basic Markdown syntax and most extended syntax, including tables, code blocks, and footnotes.

You can define a GraphQL code block with the following syntax:

```graphql
query MyQuery {
  users {
    id
    name
  }
}
```

This renders the code block with buttons to copy an operation or open it in the Explorer.

README shortcodes Copy Section

The README supports a set of shortcodes. These shortcodes can populate the README with data specific to your variant, like the graph's name and the variant's graph ref:

# Overview of {{ graph.name }}

Graph ref: {{ graph.ref }}

For a list of all supported shortcodes, click Graph shortcodes in the bottom-left corner of the README editor.

The Schema page Copy Chapter

A graph variant's Schema page has three distinct views:

• The Reference tab lets you filter your schema's type and field definitions
• The SDL tab displays your schema's raw SDL
• The ** Visualization** tab provides a filterable, navigable, graphical representation of your schema

Schema reference Copy Section

The Reference tab on the Schema page lists the different kinds of definitions in your schema, for example, objects, scalars, interfaces, etc.

Select a kind of definition to view a table of all corresponding types:

Each type definition in the table includes:

• The type's name
  • You can click the name to view additional details for the type, such as fields for an object, or possible types for a union.
• The type's description, if your schema includes one
• Which subgraphs define the type, if you have a federated supergraph
  • Users with the Consumer role can't view subgraph details.

Filtering your schema

The top of the Schema page provides a Filter Schema box you can use to find types and fields that match a set of filters:

Any filters you set remain active as you move between definitions on the Schema page.

You can filter your schema definitions by type/field name, as shown above, along with any combination of the following:

Valid only for federated supergraphs. | subgraph:products,reviews |
| ##### tag | If your graph uses the @tag directive, include results that have a @tag with any of the specified names. If viewing a table of objects, also include objects with at least one field that has a specified @tag.

If your graph doesn't use the @tag directive, this filter isn't available. | tag:internal,experimental |
| ##### directive | Include results that have any of the specified directives applied. If viewing a table of objects, also include objects with at least one field that has a specified directive. | directive:deprecated,unused |
| ##### returnType | Include results with any of the specified return types. If viewing a table of objects, include objects with at least one field that has a specified return type.

This filter includes all fields that return a particular type, regardless of each field's nullability or whether it returns a list. For example, if you specify returnType:Int, the filter includes fields that return any of Int, Int!, or [Int]. | returnType:Int,String |
| ##### argument | Include results that take a GraphQL argument with any of the specified names. If viewing a table of objects, include objects with at least one field that takes a specified argument. | argument:offset,limit |

Filtering rules

• If you list multiple possible values in a single filter, those values use OR logic.
  • For example, if you filter by subgraph:products,reviews the result includes definitions from each subgraph.
• If you apply multiple types of filters, those filters use AND logic.
  • For example, if you filter by subgraph:products and returnType:Int, the result includes only definitions that fulfill both criteria.
• Currently, it isn't possible to use AND logic for multiple filters of the same type.
  • For example, it isn't possible to filter by subgraph:products AND subgraph:reviews to include only definitions that are present in both subgraphs.

Schema definition language Copy Section

The SDL tab displays the raw schema definition language (SDL) for each schema associated with your graph. For a monograph, this is simply the graph's API schema. Supergraphs also include a supergraph schema and subgraph schemas. See Viewing subgraph SDL for more information.

Regardless of the SDL type you're viewing, you can Copy the SDL or download it in Raw or JSON format from this tab.

Schema visualization Copy Section

The Visualization tab provides a graphical representation of your schema's structure, including types, fields, and relationships.
It can help clarify your understanding of your schema's design, so you can more easily identify potential issues and improve your data model.

The Explorer Copy Chapter

GraphOS Studio provides a powerful Explorer IDE that helps you visualize your graph and run queries against it. It's available from your graph's Explorer page in Studio. Refer to the Explorer docs to learn more.

Tracking schema changes Copy Chapter

The Changelog page in Studio displays a timeline of changes made to your graph's schema.
Only schema changes that you publish to Studio are in this timeline, which is one of the most important reasons to include schema publishing in your continuous delivery pipeline.

File: src/content/graphos/basics/graphs/updating.mdx Copy Chapter

title: Updating Your Graph Safely subtitle: Upgrade your components in the recommended order to avoid errors Copy Chapter

Your supergraph consists of multiple components that are each versioned independently:

flowchart LR;
  subgraph "GraphOS";
  router(["GraphOS Router"]);
  pipeline[["🛠<br/>Build<br/>pipeline"]];
  end;
  subgraph "Your infrastructure";
  products[Subgraph A];
  reviews[Subgraph B]
  router --- products & reviews
  end;

• The GraphOS Router is based on a version of the Apollo Router Core.
  • This is true for all supergraph types (cloud and self-hosted).
• The GraphOS build pipeline uses a particular version of Apollo Federation to compose your router's supergraph schema.
  • If you use the Rover CLI to compose your supergraph schema, this is true for Rover as well. In this case, you effectively maintain your own build pipeline.
• Your subgraph schemas might each use special directives that were first introduced in a particular version of Apollo Federation.

These components each target support for a particular version of Apollo Federation, the architecture that underpins every supergraph. Because of this, it's important to make sure these various Federation versions remain compatible with each other as you make updates to individual components.

Recommended update order Copy Chapter

To avoid runtime or composition errors, your supergraph's components should always maintain the following relationship between their targeted Apollo Federation versions:

To maintain this relationship, always update these supergraph components in order from left to right:

graph LR;
  router(1. Router)
  router --> pipeline(2. Build Pipeline);
  pipeline --> subgrahs(3. Subgraph Schemas);

1. Update your router Copy Chapter

The method you use to update your router depends on which type of supergraph you have:

• If you have a self-hosted supergraph, you download the latest Apollo Router Core binary in every environment where your router runs.

• If you have a cloud supergraph, GraphOS automatically updates your router to the latest supported version whenever that version changes.

  • You can see which router version you're running from the Cloud Router section of your variant's Settings page in Studio:

For details on each router version's corresponding Apollo Federation version, see this article.

2. Update your build pipeline Copy Chapter

Whenever you make an operational change to your graph (such as publishing changes to a subgraph schema), GraphOS initiates a build that composes your graph's new supergraph schema. From GraphOS Studio, you can configure which version of Apollo Federation the build pipeline uses to perform this composition.

1. Go to your variant's Settings page, then find the General > Build Pipeline section.

2. Click Upgrade.

3. In the dialog that appears, select a Federation version from the dropdown and click Save.

GraphOS immediately initiates a new build using the selected Federation version. All future builds also use the selected version.
Successful build completion triggers a launch that delivers an updated schema to your router.

Composing with the Rover CLI Copy Section

If you host your own GraphOS Router instance, you can use the Rover CLI to compose its supergraph schema via the rover supergraph compose command.

If you do perform composition with rover supergraph compose, the command uses the exact version of composition you specify via the federation_version key in the YAML configuration file you pass:

rover supergraph compose --config ./supergraph.yaml

federation_version: =2.3.2 #highlight-line
subgraphs:
  # ...

This value must target a specific patch release (2.3.1, 2.3.2, etc.), and it must start with an equals sign (=).

3. Update subgraph schemas (as needed) Copy Chapter

After both your router and your build pipeline support a particular minimum version of Apollo Federation, your subgraphs can use features that were first introduced in that version.

As an example, the @interfaceObject directive was first introduced in Federation 2.3. To start using this directive in a subgraph, do the following:

1. Make sure your chosen subgraph library has added support for the @interfaceObject directive by consulting this table.

   • If your library doesn't yet support the directive, reach out to its maintainers about adding support.

2. Upgrade to the latest version of your subgraph library to make sure you're using a version that supports @interfaceObject.

3. Modify the following @link directive in your subgraph schema (or add it if it isn't present yet):

   graphql Copy

   extend schema
     @link(
       url: "https://specs.apollo.dev/federation/v2.3"
       import: ["@key", "@shareable", "@interfaceObject"]
     )

   Notice that the url argument targets v2.3 of the Apollo Federation spec, and @interfaceObject is included in the import list.

4. Apply the @interfaceObject directive to relevant locations in your subgraph schema.

Because you've already updated your router and build pipeline, the next time you deploy your subgraph and publish its schema to GraphOS, every component in your supergraph will be prepared to interact with a schema that includes the @interfaceObject directive you've added.

Why is this update order necessary? Copy Chapter

GraphOS supergraphs use the Apollo Federation 2 architecture. Federation 2 is itself a versioned technology (2.2, 2.3, etc.), and each version introduces changes and additions to the set of supported subgraph directives.

• Each version of the GraphOS Router is compiled against a particular version of Federation 2 (for details, see this table). Any given router version is backward compatible with previous versions of Federation. However, it isn't compatible with newer versions.

  Therefore, it's important to update your router first, before any other supergraph component begins using a later Federation 2 version. Otherwise, you might cause your router to break by providing it a supergraph schema that it doesn't support.

• Your graph's Supergraph Pipeline Track setting in GraphOS Studio determines which version of Federation 2 is used to compose your supergraph schema. This composition process fails if one of your subgraph schemas uses a directive that was introduced in a Federation version later than your chosen pipeline track.

  • In the case of a failed build, GraphOS continues to provide your router with the supergraph schema from the most recent successful build.

• Finally, subgraph schemas are where you actually apply new Federation 2 directives. You need to update your subgraph library to a version that recognizes all directives that you use in your schema.

  You perform this update last to make sure that every other component of your supergraph is prepared to interact with any newly introduced directives.

File: src/content/graphos/basics/operations/defer.mdx Copy Chapter

title: Deferring Query Response Data subtitle: Using the @defer directive Copy Chapter

With GraphOS, your supergraph's router can defer returning data for certain fields in your schema. This enables a querying client to receive non-deferred data more quickly, because the router can return it immediately instead of waiting for all response data to be ready:

sequenceDiagram
  Client->>Router: Sends a query that<br/>defers some fields
  Note over Router: Resolves non-deferred<br/>fields
  Router->>Client: Returns data for<br/>non-deferred fields
  Note over Router: Resolves deferred<br/>fields
  Router->>Client: Returns data for<br/>deferred fields

Both cloud supergraphs and self-hosted supergraphs support deferring fields with the router. Additionally, this feature is compatible with all supported subgraph libraries, because the logic resides entirely within the router!

How do I defer fields in a query? Copy Chapter

If you're using a defer-compatible client, you apply the @defer directive to fragments in your queries to specify which fields you want to defer:

query GetTopProductsAndReviews {
  topProducts {
    id
    name
    # highlight-start
    # You always apply @defer to a fragment, not to individual fields
    ... @defer {
      reviews {
        score
      }
    }
    # highlight-end
  }
}

When your supergraph's router receives this query, it defers every field in these fragments that it's able to.

Which fields can my router defer? Copy Chapter

Your supergraph's router can defer the following fields in your schema:

• Root fields of the Query type (along with their subfields)
• Fields of any entity type (along with their subfields)
  • Deferring entity fields is extremely powerful but requires some setup if you aren't using entities already. This is covered in more detail below.

See below for more information on each of these.

`Query` fields Copy Section

Your router can defer any field of your schema's Query type, along with any subfields of those fields:

query GetUsersAndDeferProducts {
  users {
    id
  }
  # highlight-start
  ... @defer {
    products {
      id
    }
  }
  # highlight-end
}

With the query above, the router first returns a list of User IDs, then later completes the response with a list of Product IDs.

Entity fields Copy Section

Your router supports deferring fields of the special object types in your supergraph called entities.

Entities are object types that often define their fields across multiple subgraphs (but they don't have to). You can identify an entity by its use of the @key directive. In the example subgraph schemas below, the Product type is an entity:

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

type Query {
  topProducts: [Product!]!
}

type Product @key(fields: "id") {
  id: ID!
  reviews: [Review!]!
}

type Review {
  score: Int!
}

Entities are query entry points into your subgraphs, and this is what enables your router to defer their fields: the router can send a followup query to a subgraph to fetch any entity fields that it doesn't fetch initially.

Here's an example query that defers entity fields using the subgraphs above:

query GetProductsAndDeferReviews {
  topProducts {
    id
    name
    # highlight-start
    ... @defer {
      reviews {
        score
      }
    }
    # highlight-end
  }
}

To handle this query, the router first resolves and returns a list of Product objects with their IDs and names. Later, the router completes the response by returning review scores for each of those products.

Defining entities in your subgraphs Copy Section

If your subgraphs don't yet include any entities, you need to define some before clients can start deferring their fields in queries.

To learn about creating entities, see this article.

Requirements for `@defer` Copy Chapter

To use @defer successfully, your supergraph and its clients must meet the requirements listed below. These requirements are divided between general requirements (requirements for using @defer at all) and entity-specific requirements (additional requirements for using @defer with entity fields).

General requirements Copy Section

• Clients must support receiving deferred query responses as multipart HTTP responses.
  • This functionality is currently supported in Apollo Client for Web and Kotlin (experimental).
• Your supergraph must be one of:
  • A cloud supergraph
  • A self-hosted supergraph running the GraphOS Router

Entity-specific requirements Copy Section

• Your subgraphs must each use a subgraph-compatible GraphQL server library.
• You must define one or more entities in your subgraph schemas.
• Each subgraph must define a reference resolver for each of its entities (or implement the corresponding functionality in your chosen subgraph library).
  • This is what enables the router to directly access entity fields with followup sub-queries.

File: src/content/graphos/basics/operations/persisted-queries.mdx Copy Chapter

title: Safelisting with Persisted Queries subtitle: Secure your graph while minimizing request latency Copy Chapter

dramatically. | 🌟 Registered persisted queries share the same performance enhancement mechanism as APQs. Additionally, they
    benefit from query plan [cache warm-ups](/router/configuration/in-memory-caching/#cache-warm-up),
    which are active by default from version
    [1.31.0](https://github.com/apollographql/router/releases/tag/v1.31.0) of the router. |

operations. |

persisted queries at the appropriate [security level](#security-level). | Platform team |

*This step provides performance benefits but isn't necessary for safelisting.* | App developers |

{
  "format": "apollo-persisted-query-manifest",
  "version": 1,
  "operations": [
    {
      "id": "dc67510fb4289672bea757e862d6b00e83db5d3cbbcfb15260601b6f29bb2b8f",
      "body": "query UniversalQuery { __typename }",
      "name": "UniversalQuery",
      "type": "query"
    },
    {
      "id": "f11e4dcb28788af2e41689bb366472084aa1aa1e1ba633c3d605279cff08ed59",
      "body": "query FragmentedQuery { post { ...PostFragment } }  fragment PostFragment on Post { id title }",
      "name": "FragmentedQuery",
      "type": "query"
    }
  ]
}

apollo {
  service("myapi") {
    packageName.set("com.example.myapi")
    operationManifestFormat.set("persistedQueryManifest") //highlight-line
  }
}

{
  "variables": null,
  "extensions": {
    "persistedQuery": {
      "version": 1,
      "sha256Hash": "PQL_ID_HERE"
    }
  }
}

graph LR;

  subgraph "CI/CD"
  webClient("Web client<br/>build");
  androidClient("Android client<br/>build");
  iosClient("iOS client<br/>build");
  end

  subgraph "GraphOS"
  pql[[Persisted<br/>Query List]];
  end

  webClient & androidClient & iosClient -->|Publishes<br/>operations|pql

{
  "format": "apollo-persisted-query-manifest",
  "version": 1,
  "operations": [
    {
      "id": "dc67510fb4289672bea757e862d6b00e83db5d3cbbcfb15260601b6f29bb2b8f",
      "body": "query UniversalQuery { __typename }",
      "name": "UniversalQuery",
      "type": "query"
    }
  ]
}

{
  "id": "dc67510fb4289672bea757e862d6b00e83db5d3cbbcfb15260601b6f29bb2b8f",
  "body": "query UniversalQuery { __typename }",
  "name": "UniversalQuery",
  "type": "query"
}

query GetBooks {
  books {
    publishDate
    title
  }
}

query GetBooks {
  books {
    #highlight-start
    title
    publishDate
    #highlight-end
  }
}

query GetBooks($limit: Int, $offset: Int) {
  books(limit: $limit, offset: $offset) {
    title
  }
}

query GetBooks($limit: Int, $offset: Int) {
  #highlight-start
  books(offset: $offset, limit: $limit) {
    #highlight-end
    title
  }
}

query GetBooks {
  books {
    author
    title
  }
}

query GetBooks {
  books {
    author
    title
    __typename #highlight-line
  }
}

subscription OnStockPricesChanged {
  stockPricesChanged {
    symbol
    price
  }
}

type Subscription {
  stockPricesChanged: [Stock!]!
}

subscription:
  enabled: true
  mode:
    passthrough:
      all:
        path: /ws

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

# highlight-start
type Subscription {
  productPriceChanged: Product!
}
#highlight-end

type Product @key(fields: "id") {
  id: ID!
  reviews: [Review!]!
}

type Review {
  score: Int!
}

subscription OnProductPriceChanged {
  productPriceChanged {
    # Defined in Products subgraph
    name
    price
    reviews {
      # Defined in Reviews subgraph!
      score
    }
  }
}

subscription {
  productPriceChanged {
    id # Added for entity fetching
    name
    price
    # Reviews fields removed!
  }
}

query {
  _entities(representations: [...]) {
    ... on Product {
      reviews {
        score
      }
    }
  }
}

curl 'https://main--my-org-supergraph.apollographos.net/graphql' -v \
  -H 'accept: multipart/mixed; boundary="graphql"; subscriptionSpec=1.0, application/json' \
  -H 'content-type: application/json' \
  --data-raw '{"query":"subscription OnProductPriceChanged { productPriceChanged { name price reviews { score } } }","operationName":"OnProductPriceChanged"}'

--graphql
content-type: application/json

{}
--graphql
content-type: application/json

{"payload":{"data":{"productPriceChanged":{"name":"Croissant","price":400,"reviews":[{"score":5}]}}}}
--graphql
content-type: application/json

{"payload":{"data":{"productPriceChanged":{"name":"Croissant","price":375,"reviews":[{"score":5}]}}}}
--graphql
content-type: application/json

{"payload":{"data":{"productPriceChanged":{"name":"Croissant","price":425,"reviews":[{"score":5}]}}}}
--graphql--