Merge pull request #486 from apollographql/sb/graphos-docs-tidy

Miscellaneous GraphOS docs tidying

src/content/graphos/basics/api-keys.mdx

@@ -1,12 +1,14 @@
 ---
 title: API keys
-description: In GraphOS
+description: For Apollo GraphOS
 ---
 
 import ObtainGraphApiKey from '../../shared/obtain-graph-api-key.mdx';
 import ObtainPersonalApiKey from '../../shared/obtain-personal-api-key.mdx';
 
-Every application that sends data to Apollo GraphOS must use an **API key** to do so. Apollo Studio enables you to create and manage two types of API keys: **graph API keys** and **personal API keys**. Every system that _isn't_ running as part of your local development setup should always use a graph API key.
+Every system that communicates with Apollo GraphOS must use an **API key** to do so. [GraphOS Studio](https://studio.apollographql.com/?referrer=docs-content) enables you to create and manage two types of API keys: **graph API keys** and **personal API keys**.
+
+Any system that _isn't_ running as part of your local development setup should always use a graph API key.
 
 ## Graph API keys
 
@@ -28,6 +30,6 @@ You can't change a graph API key's role after it's created. Instead, create a ne
 
 A personal API key provides partial access to **every graph in every organization you belong to**. Specifically, it has the same permissions that your user account has in each of those organizations.
 
-Personal API keys are useful for local development tools (like the [Rover CLI](/rover/) and the Apollo [VS Code extension](/devtools/editor-plugins/)) to load schemas and other data from Studio.
+Personal API keys are useful for local development tools (like the [Rover CLI](/rover/) and the Apollo [VS Code extension](/devtools/editor-plugins/)) to load schemas and other data from GraphOS.
 
 <ObtainPersonalApiKey />

src/content/graphos/basics/index.mdx

@@ -5,22 +5,26 @@ description: The GraphQL developer platform
 
 import {Link} from 'gatsby';
 
-**Apollo GraphOS** is the cloud platform for building, growing, and collaborating on your organization's **supergraph**, an organization-wide data layer powered by GraphQL.
+**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.
 
 ```mermaid
 flowchart LR;
  clients("GraphQL<br/>Clients");
  subgraph "<b>Apollo GraphOS</b>";
  registry(["Schema<br/>Registry"]);
- router(["Supergraph<br/>Router"]);
+ router(["Graph<br/>Router"]);
  studio(["Studio UI"]);
  end;
  subgraph "Your infrastructure";
  products["GraphQL API<br/>A"];
  reviews["GraphQL API<br/>B"];
- router --- products & reviews
+ router -->|Sub-query| products & reviews
+ dbA[( )];
+ dbB[( )];
+ products --- dbA;
+ reviews --- dbB;
  end;
- clients -.- router;
+ clients -.->|Query| router;
  class clients secondary;
 ```
 

src/content/graphos/delivery/index.mdx

@@ -12,9 +12,11 @@ Whenever you make changes to a graph's schema, you should **publish** those chan
 
 ## Subgraph schemas
 
-Every supergraph in GraphOS includes one or more subgraphs. You _individually_ publish each subgraph's schema to Apollo with `rover subgraph publish`:
+Every supergraph in GraphOS includes one or more **subgraphs**. These are the individual GraphQL-powered microservices in your organization.
 
-```bash
+You _individually_ publish each subgraph's schema to Apollo with `rover subgraph publish`:
+
+```bash title="Example command"
 rover subgraph publish --schema ./products.graphql --name products docs-example-graph@current --routing-url https://products.example.com
 ```
 
@@ -32,7 +34,7 @@ graph LR;
 
 **To publish a subgraph schema to Apollo:**
 
-1. Identify the name of the subgraph you're publishing to. You can view the names of your existing subgraphs from your variant's **Subgraphs** page in Apollo Studio.
+1. Identify the name of the subgraph you're publishing to. You can view the names of your existing subgraphs from your variant's **Subgraphs** page in [GraphOS Studio](https://studio.apollographql.com/?referrer=docs-content).
 
 2. **If you're publishing a subgraph for the first time,** _also_ obtain the **routing URL** for that subgraph. This is the URL that your router will use to communicate with the subgraph.
 
@@ -64,7 +66,7 @@ graph TB;
 
 If this composition succeeds, your router is updated with the result. This enables clients to query any newly added fields, and it _prevents_ them from querying any _removed_ fields.
 
-> You can manually fetch your router's latest supergraph schema with the `rover supergraph fetch` command, or retrieve it from your supergraph's **Schema > SDL** page in Apollo Studio.
+> You can manually fetch your router's latest supergraph schema with the `rover supergraph fetch` command, or retrieve it from your supergraph's **Schema > SDL** page in GraphOS Studio.
 
 ## Publishing with continuous delivery
 

src/content/graphos/explorer/embed-explorer.mdx

@@ -2,7 +2,7 @@
 title: Embedding the Explorer
 ---
 
-You can embed the [Apollo Studio Explorer](./) in a webpage that you can then provide to your graph's consumers. This enables those consumers to test out operations from your own website.
+You can embed the [GraphOS Studio Explorer](./) in a webpage that you can then provide to your graph's consumers. This enables those consumers to test out operations from your own website.
 
 For example, here's an embedded Explorer for an Apollo example graph. Try it out!
 
@@ -37,9 +37,7 @@ For more information, see the [landing page plugin API reference](/apollo-server
 
 ## Embedding on an arbitrary webpage
 
-1. <a href="https://studio.apollographql.com/" target="_blank">
- Go to Apollo Studio
- </a> and open the variant you want to use with the embedded Explorer.
+1. [Open GraphOS Studio](https://studio.apollographql.com/?referrer=docs-content) and select the graph variant you want to use with the embedded Explorer.
 
 2. Go to the variant's Explorer page.
 

src/content/graphos/explorer/index.mdx

@@ -9,6 +9,8 @@ The GraphOS Studio Explorer is a powerful web IDE for creating, running, and man
 
 The Explorer is free for all GraphOS organizations. It supports all GraphQL operation types (`Query`, `Mutation`, and [`Subscription`](./subscriptions-explorer/)).
 
+> The Explorer is also available in a [sandbox mode](./sandbox/) that doesn't require an Apollo account.
+
 ## Setup
 
 To get started with the Explorer, [create a graph](../quickstart/cloud/#2-create-your-first-supergraph) in Apollo Studio and then navigate to that graph's Explorer page:
@@ -19,8 +21,6 @@ To get started with the Explorer, [create a graph](../quickstart/cloud/#2-create
  alt="The default Explorer view for a new supergraph"
 />
 
-> The Explorer also provides a [sandbox mode](./sandbox/) that doesn't require an Apollo account.
-
 ## Building a query
 
 Here's an example [embedded Explorer](./embed-explorer/) you can use to try out the query-building features described below!

src/content/graphos/explorer/operation-collections.mdx

@@ -3,7 +3,7 @@ title: Operation collections in the Explorer
 description: Save and share frequently used GraphQL operations
 ---
 
-You can create **operation collections** in the Apollo Studio Explorer, enabling you to save, organize, and share your organization's frequently used GraphQL operations:
+You can create **operation collections** in the GraphOS Studio Explorer, enabling you to save, organize, and share your organization's frequently used GraphQL operations:
 
 <img
  src="../img/operation-collections/list-collections.jpg"

src/content/graphos/explorer/sandbox.mdx

@@ -3,7 +3,7 @@ title: Apollo Sandbox
 description: Use Studio tools without an Apollo account
 ---
 
-**Apollo Sandbox** is a special mode of Apollo Studio that helps with local development. Sandbox loads a running GraphQL server's schema via introspection, instead of fetching published schemas from the Apollo registry.
+**Apollo Sandbox** is a special mode of GraphOS Studio that helps with local development. Sandbox loads a running GraphQL server's schema via introspection, instead of fetching published schemas from the Apollo registry.
 
 Sandbox provides access to the following Apollo Studio features:
 
@@ -49,7 +49,7 @@ You can also change the default endpoint by providing a [URL parameter](#url-par
 
 ## Schema diffs
 
-If you log in to Apollo Studio from Sandbox, you can diff your Sandbox schema against any subgraph or monolith graph you have access to in the Apollo registry.
+If you log in to GraphOS Studio from Sandbox, you can diff your Sandbox schema against any subgraph or monolith graph you have access to in the GraphOS schema registry.
 
 From [Sandbox](https://studio.apollographql.com/sandbox/), open the **Schema Diff** page from the left navigation panel. Then use the dropdown menus to select any accessible organization, graph, and variant to compare against:
 
@@ -65,7 +65,7 @@ In addition to viewing the diff on this page, you can click **Run a Check** in t
 
 ## Schema checks
 
-If you log in to Apollo Studio from Sandbox, you can run [schema checks](../delivery/schema-checks/) between your Sandbox schema and any graph you have access to in the Apollo registry.
+If you log in to GraphOS Studio from Sandbox, you can run [schema checks](../delivery/schema-checks/) between your Sandbox schema and any graph you have access to in the Apollo registry.
 
 > Organization members with the [**Consumer** role](../org/members/#organization-wide-member-roles) cannot run schema checks.
 
@@ -115,9 +115,9 @@ You can use Sandbox _without_ an internet connection if you're querying a graph
 
 ### Reconnecting
 
-Sandbox automatically reconnects whenever your internet connection is restored. When it does, it might display a notification that your Apollo Studio application version is stale by at least 24 hours. You can click the notification to update _all_ of your browser's open Apollo Studio tabs to the latest version.
+Sandbox automatically reconnects whenever your internet connection is restored. When it does, it might display a notification that your GraphOS Studio application version is stale by at least 24 hours. You can click the notification to update _all_ of your browser's open Studio tabs to the latest version.
 
-> This notification indicates only that the Apollo Studio _UI_ is out of date. Your Studio _data_ is always kept up to date.
+> This notification indicates only that the GraphOS Studio _UI_ is out of date. Your Studio _data_ is always kept up to date.
 
 ## Operation collections in Sandbox
 
@@ -138,7 +138,7 @@ The following URL parameters are supported:
 
 For example, the following URL sets all supported parameters:
 
-```
+```text title="Example URL"
 https://studio.apollographql.com/sandbox/explorer?endpoint=http://localhost:4200&document=query hello($name: String!) { hello(name: $name)}&variables={"name": "Sandbox User"}&headers={"Cache-Control": "no-cache"}
 ```
 
@@ -181,7 +181,7 @@ You can embed Sandbox on your own website. This can be useful for interacting wi
  width="600"
  />
 
-3. Within the dialog, use the tabs to select the code snippet for your use case:
+3. In the dialog, use the tabs to select the code snippet for your use case:
 
  * Use **React** for React apps where you can `npm install` the `@apollo/sandbox` package.
  * Use **JavaScript** for non-React JavaScript apps where you can `npm install` the `@apollo/sandbox` package.

src/content/graphos/metrics/field-usage.mdx

@@ -1,11 +1,11 @@
 ---
-title: Measuring field usage in Apollo Studio
+title: Measuring field usage with GraphOS Studio
 description: Understand which fields your clients use
 ---
 
-> For details on setting up field metrics reporting to Apollo Studio, see [Reporting field usage](#reporting-field-usage).
+> For details on setting up field metrics reporting to GraphOS Studio, see [Reporting field usage](#reporting-field-usage).
 
-In Apollo Studio, your graph's **Fields** page can display a table of basic usage metrics for each field in your schema:
+In [GraphOS Studio](https://studio.apollographql.com/?referrer=docs-content), your graph's **Fields** page can display a table of basic usage metrics for each field in your schema:
 
 <img
  src="../img/fields-page.jpg"
@@ -24,14 +24,14 @@ You can click the name of any field in the table to open its **Field Insights**
 
 ## Field executions vs. requesting operations
 
-The table on the Fields page displays some combination of the following metrics for each field, depending on which data your graph reports to Studio:
+The table on the Fields page displays some combination of the following metrics for each field, depending on which data you report to GraphOS:
 
 | Metric | Description |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
 | Field executions | How many times your servers have executed the resolver for the field over a given time period. |
 | Requested by operations | How many operations sent by clients over a given time period have included the field, according to metrics provided by your servers. |
 
-For each of these columns to appear on the Fields page, your GraphQL servers must [report the associated metrics to Apollo Studio](#reporting-field-usage). If some but not _all_ of your GraphQL servers report this data, the Fields page presents an incomplete picture of your graph's field usage.
+For each of these columns to appear on the Fields page, your GraphQL servers must [report the associated metrics to GraphOS](#reporting-field-usage). If some but not _all_ of your GraphQL servers report this data, the Fields page presents an incomplete picture of your graph's field usage.
 
 Let's look at these two metrics for fields of an example type:
 
@@ -62,8 +62,7 @@ If `Query.books` returns a list of ten `Book` objects, then `Book.title` is reso
 
 Let's say a client executes the following query one time:
 
-```
-graphql
+```graphql
 query GetTwoBooks {
  firstBook: book(id: "123") {
  title
@@ -194,15 +193,15 @@ Your GraphQL server can report metrics for field executions, requesting operatio
 
 ### Prerequisites
 
-> ⚠️ Before continuing, make sure you've configured your Apollo Gateway or individual GraphQL server to [push metrics to GraphOS](./sending-operation-metrics/).
+> ⚠️ Before continuing, make sure you've configured your router or individual GraphQL server to [push metrics to GraphOS](./sending-operation-metrics/).
 
-To report each type of field usage metric to Apollo, make sure your graph meets the prerequisites for that metric:
+To report each type of field usage metric to GraphOS, make sure your graph meets the prerequisites for that metric:
 
 #### Requesting operations
 
 To report metrics for requesting operations, your GraphQL server must run Apollo Server 3.6 or later.
 
-If you have a [federated graph](https://apollographql.com/docs/federation), your _gateway_ must run Apollo Server 3.6 or later, but there are no requirements for your subgraphs.
+If you have a [federated graph](/federation), your _gateway_ must run Apollo Server 3.6 or later, but there are no requirements for your subgraphs.
 
 #### Field executions
 

src/content/graphos/metrics/index.mdx

@@ -11,7 +11,7 @@ In addition, you can configure your subgraphs to include [resolver-level traces]
 
 ## Viewing metrics
 
-You can visualize operation metrics in Apollo Studio, from any variant's **Operations** page:
+You can visualize operation metrics in [GraphOS Studio](https://studio.apollographql.com/?referrer=docs-content), from any variant's **Operations** page:
 
 <img
  src="../img/studio-metrics.jpg"
@@ -29,7 +29,7 @@ The page displays _overall_ values for these metrics, along with values broken d
 
 ## Resolver-level traces
 
-If you [enable trace reporting](#enabling-traces) in your subgraphs, Apollo Studio can also display resolver-level trace information about each operation:
+If you [enable trace reporting](#enabling-traces) in your subgraphs, GraphOS Studio can also display resolver-level trace information about each operation:
 
 <img
  src="../img/traces-tab.jpg"

src/content/graphos/metrics/notifications/build-status-notification.md

@@ -4,13 +4,13 @@ title: Build status notifications (preview)
 
 > Build status notifications require an [Enterprise plan](https://www.apollographql.com/pricing/). They are currently in preview.
 
-You can [configure Apollo Studio](./notification-setup) to notify your team via webhook whenever Apollo attempts to build a new supergraph schema for your [federated graph](/federation/). The notification indicates whether the build succeeded and provides a temporary URL to the new supergraph schema if so.
+You can [configure GraphOS](./notification-setup) to notify your team via webhook whenever GraphOS attempts to build a new supergraph schema for your [federated graph](/federation/). The notification indicates whether the build succeeded and provides a temporary URL to the new supergraph schema if so.
 
 You can configure separate change notifications for each [variant](../../graphs/#variants) of your graph.
 
 ## Setup
 
-See [Setting up Studio Notifications](./notification-setup).
+See [Setting up GraphOS Notifications](./notification-setup).
 
 ## Webhook format
 

src/content/graphos/metrics/notifications/daily-reports.md

@@ -2,15 +2,15 @@
 title: Daily reports from Apollo Studio
 ---
 
-You can [configure Apollo Studio](./notification-setup/) to send your team a daily summary of your graph's activity over the last 24 hours:
+You can [configure GraphOS](./notification-setup/) to send your team a daily summary of your graph's activity over the last 24 hours:
 
 <img src="../../img/integrations/slack-report.png" width="400" alt="Slack daily report" class="screenshot" />
 
 When you configure daily reports, you can specify what time you want to receive them each day.
 
 ## Setup
 
-See [Setting up Studio Notifications](./notification-setup).
+See [Setting up GraphOS Notifications](./notification-setup).
 
 ## Acting on report data
 

src/content/graphos/metrics/notifications/notification-setup.md

@@ -1,21 +1,21 @@
 ---
-title: Setting up Apollo Studio notifications
+title: Setting up GraphOS notifications
 ---
 
-Apollo Studio can notify your team about changes to your graph and its performance. These notifications help you stay up to date and address issues as they arise.
+GraphOS can notify your team about changes to your graph and its performance. These notifications help you stay up to date and address issues as they arise.
 
-> If you don't have an Apollo Studio organization yet, [get started](../../quickstart/cloud/).
+> If you don't have a GraphOS organization yet, [get started](../../quickstart/cloud/).
 
 ## Supported notifications and channels
 
-Studio can send your team the following notification types:
+GraphOS can send your team the following notification types:
 
 - [Daily reports](./daily-reports) of your graph's request rate, error rate, and latency
 - [Schema change notifications](./schema-change-integration) whenever your graph's schema is updated
 - [Performance alerts](./performance-alerts) whenever a metric such as error percentage or request latency exceeds a particular threshold (this experimental feature requires a [paid plan](https://www.apollographql.com/pricing/))
 - [Build status notifications](./build-status-notification) whenever Apollo attempts to compose a supergraph schema for your federated graph (this preview feature is [enterprise only](https://www.apollographql.com/pricing/))
 
-Currently, Studio can send each of these notification types to the channel(s) indicated:
+Currently, GraphOS can send each of these notification types to the channel(s) indicated:
 
 | Notification Type | Slack | Pagerduty | Custom Webhook |
 | :------------------------------------------- | :---: | :-------: | :------------: |
@@ -28,7 +28,7 @@ Currently, Studio can send each of these notification types to the channel(s) in
 
 > For performance alerts, see [Performance alerts setup](./performance-alerts/#setup).
 
-1. Go to your graph's Settings page in [Apollo Studio](https://studio.apollographql.com/).
+1. Go to your graph's Settings page in [GraphOS Studio](https://studio.apollographql.com/?referrer=docs-content).
 2. Select the **Reporting** tab.
 3. Click **Add notification** in the upper right:
  <img src="../../img/add-new-alert.jpg" class="screenshot" width="500" alt="Add new alert button" />