From d0c1c6b334e0a1d55ff354b1c3268a9d37dd69cc Mon Sep 17 00:00:00 2001 From: Stephen Barlow Date: Sat, 8 Apr 2023 17:01:21 -0500 Subject: [PATCH] Nomenclature cleanup throughout rover docs --- docs/source/commands/config.mdx | 2 +- docs/source/commands/contracts.mdx | 83 ++++++++++++++++++++-------- docs/source/commands/dev.mdx | 24 ++++---- docs/source/commands/graphs.mdx | 24 ++++---- docs/source/commands/readmes.mdx | 14 ++--- docs/source/commands/subgraphs.mdx | 25 ++++----- docs/source/commands/supergraphs.mdx | 5 +- docs/source/configuring.md | 14 ++--- docs/source/conventions.md | 4 +- docs/source/getting-started.md | 2 +- docs/source/index.mdx | 16 +++--- 11 files changed, 124 insertions(+), 89 deletions(-) diff --git a/docs/source/commands/config.mdx b/docs/source/commands/config.mdx index 9445ef99a..169c24088 100644 --- a/docs/source/commands/config.mdx +++ b/docs/source/commands/config.mdx @@ -3,7 +3,7 @@ title: Rover config commands description: Create and manage configuration profiles --- -The Rover CLI enables you to create multiple **configuration profiles**, each of which corresponds to a different identity in Apollo Studio. Each configuration profile has an associated [API key](/graphos/api-keys), which determines its permissions. You manage your configuration profiles with the `rover config` set of commands. +Rover enables you to create multiple **configuration profiles**, each of which corresponds to a different GraphOS identity. Each configuration profile has an associated [API key](/graphos/api-keys), which determines its permissions. You manage your configuration profiles with the `rover config` set of commands. ## Displaying configuration profiles diff --git a/docs/source/commands/contracts.mdx b/docs/source/commands/contracts.mdx index 4c2417756..33e83fce9 100644 --- a/docs/source/commands/contracts.mdx +++ b/docs/source/commands/contracts.mdx @@ -1,17 +1,32 @@ --- title: Rover contract commands -description: For use with Apollo Contract variants +description: For use with GraphOS contract variants --- -A **contract** is a variant that is the result of filtering out schema elements from a source variant. +GraphOS [contracts](/graphos/delivery/contracts/) enable you to create variants of a supergraph that filter out schema elements according to inclusion and exclusion rules: + +```mermaid +graph LR; + subgraph "Source variant"; + api("Supergraph
schema
▉"); + end + subgraph "Contract variant B" + contractB("Contract schema B
▟") + end + subgraph "Contract variant A" + contractA("Contract schema A
▛"); + end + api -."Filter schema
according to contract A".->contractA + api -."Filter schema
according to contract B".->contractB +``` -Rover commands that interact with [contracts](https://www.apollographql.com/docs/graphos/delivery/contracts/) begin with `rover contract`. +The `rover contract` command set enables you to interact with your existing contracts and create new ones. -## Publishing a contract to Apollo Studio +## Publishing a contract to GraphOS ### `contract publish` -> This command requires [authenticating Rover with Apollo Studio](../configuring/#authenticating-with-apollo-studio). +> This command requires [authenticating Rover with GraphOS](../configuring/#authenticating-with-graphos). You can use Rover to publish a new contract or publish configuration changes to an existing contract. @@ -26,9 +41,9 @@ rover contract publish my-graph@my-contract-variant \ --hide-unreachable-types ``` -The argument `my-graph@my-contract-variant` in the example above is a [graph ref](../conventions/#graph-refs) that specifies the ID of the Studio graph you're publishing to, along with which [variant](/graphos/graphs/overview/#variants) you're publishing to. +The argument `my-graph@my-contract-variant` in the example above is a [graph ref](../conventions/#graph-refs) that specifies the ID of the graph you're publishing to, along with which contract variant you're creating or modifying. -If this variant already exists in the graph registry, its configuration is updated; otherwise, a new contract variant is created. +If this contract variant already exists in the graph registry, its configuration is updated. Otherwise, a new contract variant is created. Options include: @@ -48,13 +63,13 @@ Options include: -The name of the [source variant](https://www.apollographql.com/docs/graphos/delivery/contracts/#2-fed1-enable-variant-support-for-tag) whose supergraph schema is used for filtering. +The name of the [source variant](/graphos/delivery/contracts/#2-fed1-enable-variant-support-for-tag) to use for supergraph schema filtering. -The source variant must be on the same graph as the contract variant and cannot be changed after contract creation. It must also be a federated variant with subgraphs. If your graph is using Federation 1, support for the `@tag` directive must be explicitly enabled in Studio. +The source variant must belong to the same graph as the contract variant. It must also be a federated variant with subgraphs. If your graph uses Federation 1, you must enable its support for the `@tag` directive in Apollo Studio. **Required** the first time you publish a contract. -**Optional** after your first publish, but if provided it must match the previously published source variant in Studio. +**Optional** after your first publish. If provided, it must match the value provided for the first publish (the source variant for a particular contract variant can't change). @@ -66,7 +81,13 @@ The source variant must be on the same graph as the contract variant and cannot -**Required unless `--no-include-tags` is used.** A tag name to [include](https://www.apollographql.com/docs/graphos/delivery/contracts/#contract-filters) when filtering. To include multiple tag names, specify `--include-tag` multiple times (e.g. `--include-tag foo --include-tag bar`). To include no tag names/use an empty list, specify `--no-include-tags` instead. +A tag name to [include](/graphos/delivery/contracts/#contract-filters) when filtering. To include multiple tag names, specify `--include-tag` multiple times: + +```bash +--include-tag foo --include-tag bar +``` + +To specify an _empty_ include list, provide`--no-include-tags` instead of this option. Every tag name **must**: @@ -74,6 +95,8 @@ Every tag name **must**: * Include only letters, numbers, underscores (`_`), hyphens (`-`), or slashes (`/`). * Have a maximum of 128 characters. +One of `--include-tag` or `--no-include-tags` is **required**. + @@ -84,7 +107,9 @@ Every tag name **must**: -**Required unless `--include-tag` is used.** [Include](https://www.apollographql.com/docs/graphos/delivery/contracts/#contract-filters) no tag names when filtering. To include a non-empty list of tag names, specify `--include-tag` instead. +Specifies an empty [include list](/graphos/delivery/contracts/#contract-filters) for the published contract. + +One of `--include-tag` or `--no-include-tags` is **required**. @@ -96,7 +121,13 @@ Every tag name **must**: -**Required unless `--no-exclude-tags` is used.** A tag name to [exclude](https://www.apollographql.com/docs/graphos/delivery/contracts/#contract-filters) when filtering. To exclude multiple tag names, specify `--exclude-tag` multiple times (e.g. `--exclude-tag foo --exclude-tag bar`). To exclude no tag names/use an empty list, specify `--no-exclude-tags` instead. +A tag name to [exclude](/graphos/delivery/contracts/#contract-filters) when filtering. To exclude multiple tag names, specify `--exclude-tag` multiple times: + +``` +--exclude-tag foo --exclude-tag bar +``` + +To specify an _empty_ exclude list, provide`--no-exclude-tags` instead of this option. Every tag name **must**: @@ -104,6 +135,8 @@ Every tag name **must**: * Include only letters, numbers, underscores (`_`), hyphens (`-`), or slashes (`/`). * Have a maximum of 128 characters. +One of `--exclude-tag` or `--no-exclude-tags` is **required**. + @@ -114,7 +147,9 @@ Every tag name **must**: -**Required unless `--exclude-tag` is used.** [Exclude](https://www.apollographql.com/docs/graphos/delivery/contracts/#contract-filters) no tag names when filtering. To exclude a non-empty list of tag names, specify `--exclude-tag` instead. +Specifies an empty [exclude list](/graphos/delivery/contracts/#contract-filters) for the published contract. + +One of `--exclude-tag` or `--no-exclude-tags` is **required**. @@ -126,7 +161,9 @@ Every tag name **must**: -**Required unless `--no-hide-unreachable-types` is used.** Automatically [hide](https://www.apollographql.com/docs/graphos/delivery/contracts/#contract-filters) types that can never be reached in operations on the contract schema +If provided, the contract automatically [hides](/graphos/delivery/contracts/#contract-filters) types that are unreachable from the contract schema's root fields. + +One of `--hide-unreachable-types` or `--no-hide-unreachable-types` is **required**. @@ -138,7 +175,9 @@ Every tag name **must**: -**Required unless `--hide-unreachable-types` is used.** Do not automatically [hide](https://www.apollographql.com/docs/graphos/delivery/contracts/#contract-filters) types that can never be reached in operations on the contract schema +If provided, the contract does _not_ automatically hide types that are unreachable from the contract schema's root fields. + +One of `--hide-unreachable-types` or `--no-hide-unreachable-types` is **required**. @@ -150,20 +189,20 @@ Every tag name **must**: -**Optional.** Do not trigger a [launch](https://www.apollographql.com/docs/graphos/delivery/contracts/#review-and-launch) in Studio after updating the contract configuration +**Optional.** If provided, this command does not trigger a [launch](/graphos/delivery/contracts/#review-and-launch) in GraphOS after updating the contract configuration. -## Describing a contract variant +## Fetching contract details ### `contract describe` -> This command requires [authenticating Rover with Apollo Studio](../configuring/#authenticating-with-apollo-studio). +> This command requires [authenticating Rover with GraphOS](../configuring/#authenticating-with-graphos). -You can use Rover to describe the configuration of any contract variant that Rover has access to. +You can use Rover to fetch the configuration of any contract variant that Rover has access to. Run the `contract describe` command, like so: @@ -171,9 +210,9 @@ Run the `contract describe` command, like so: rover contract describe my-graph@my-contract-variant ``` -The argument `my-graph@my-contract-variant` in the example above is a [graph ref](../conventions/#graph-refs) that specifies the ID of the Studio graph you're fetching from, along with which [variant](/graphos/graphs/overview/#variants) you're fetching. +The argument `my-graph@my-contract-variant` in the example above is a [graph ref](../conventions/#graph-refs) that specifies the ID of the GraphOS graph you're fetching from, along with which contract variant you're fetching. -The output will contain information of how the contract variant was configured such as the source variant, include and exclude tags. +This command prints a summary of the contract's configuration, including its source variant and include/exclude lists: ``` Fetching description for configuration of my-graph@my-contract-variant using credentials from the default profile. diff --git a/docs/source/commands/dev.mdx b/docs/source/commands/dev.mdx index ba3c3cd48..b735e2115 100644 --- a/docs/source/commands/dev.mdx +++ b/docs/source/commands/dev.mdx @@ -3,7 +3,7 @@ title: The Rover dev command description: Query a locally federated GraphQL API --- -> ⚠️ **Note:** The `rover dev` command is _only_ for local development. Do **not** run this command in production. +> ⚠️ **Do not run `rover dev` in production!** This command is for local development _only_. A **subgraph** is a graph that contributes to the composition of a federated **supergraph**: @@ -16,9 +16,7 @@ graph BT; gateway --- serviceA & serviceB & serviceC; ``` -You can use Rover to start a local router that can query across one or more running GraphQL APIs (i.e., subgraphs) -through one endpoint (i.e., supergraph). As you add, edit, and remove subgraphs, Rover automatically -composes their separate schemas into a unified supergraph schema that the router reloads and serves. +You can use Rover to start a local router that can query across one or more running GraphQL APIs (i.e., subgraphs) through one endpoint. As you add, edit, and remove subgraphs, Rover automatically composes their separate schemas into a unified supergraph schema that the router reloads and serves. Think plug-n-play USB devices but with your GraphQL APIs! @@ -26,17 +24,21 @@ Think plug-n-play USB devices but with your GraphQL APIs! ### Starting the session -Before using Rover's `dev` command, you first need to have access to a running GraphQL API (subgraph). You'll need the URL the GraphQL API is serving and the location of the schema in the filesystem. If you don't have a local schema file, your subgraph must enable introspection. +Before using `rover dev`, you need at least one running GraphQL API (subgraph). You'll need the URL the GraphQL API is serving, along with the location of its schema in your filesystem. -An example `rover dev` command for running a local subgraph might look something like this: +> If you don't have a local schema file, your subgraph must enable introspection. -`rover dev --name products --schema ./products.graphql --url http://localhost:4000` +Here's an example `rover dev` command that provides a locally running subgraph: -The above command starts the `rover dev` session, watching `./products.graphql` for changes to the schema, and starts up a local Apollo Router at the default endpoint (i.e., `http://localhost:3000`). This session also listens for other `rover dev` processes that include different subgraph schemas. +```bash +rover dev --name products --schema ./products.graphql --url http://localhost:4000 +``` + +This starts the `rover dev` session, which watches `./products.graphql` for changes to the schema. It also starts up a local Apollo Router instance at its default endpoint (`http://localhost:3000`). Finally, the session listens for _other_ `rover dev` processes that include different subgraph schemas. ### Stopping the session -If you stop the first `rover dev` session (by pressing `CTRL+C`), it will shut down the router, and any attached `rover dev` processes are detached and shut down. +If you stop the first `rover dev` session (by pressing `CTRL+C`), it shuts down the local router instance. It _also_ detaches and shuts down any secondary `rover dev` processes. ### Attaching additional subgraphs to a session @@ -54,11 +56,11 @@ If you pass the `--schema ` argument, `rover dev` watches that schema file #### Via introspection -If you don't pass the `--schema ` argument, `rover dev` will introspect the URL specified by the `--url ` argument once every second. The command prefers to use the same query as `rover subgraph introspect` but falls back to `rover graph introspect` if your GraphQL API doesn't support introspecting federated SDL. If this is the case, directives are stripped from the subgraph schema. +If you don't pass the `--schema ` argument, `rover dev` introspects the URL specified by the `--url ` argument once every second. The command prefers to use the same query as `rover subgraph introspect` but it falls back to `rover graph introspect` if your GraphQL API doesn't support introspecting federated SDL. If this is the case, directives are stripped from the subgraph schema. ### Stopping an attached process -If you stop an attached `rover dev` process (by pressing `CTRL+C`), the supergraph will de-compose the removed subgraph and reload the router. +If you stop an attached `rover dev` process (by pressing `CTRL+C`), the supergraph will recompose its schema _without_ the removed subgraph and reload the router. ### Health check diff --git a/docs/source/commands/graphs.mdx b/docs/source/commands/graphs.mdx index 3f12deadf..e1a922ede 100644 --- a/docs/source/commands/graphs.mdx +++ b/docs/source/commands/graphs.mdx @@ -3,7 +3,7 @@ title: Rover graph commands description: Publish and retrieve your API schema --- -These Rover commands are _primarily_ for interacting with monolithic graphs that do _not_ use [federation](/federation/). However, you can also use them to fetch a federated graph's API schema [from Apollo Studio](#graph-fetch) or [via introspection](#graph-introspect). +These Rover commands are _primarily_ for interacting with [monographs](/graphos/graphs/overview/#monographs) that do _not_ use [federation](/federation/). However, you can also use them to fetch a federated graph's API schema [from GraphOS](#graph-fetch) or [via introspection](#graph-introspect). > To fetch a federated graph's _supergraph_ schema instead of its _API_ schema, use [`supergraph` commands](./supergraphs/). [Learn about different schema types.](/federation/federated-types/overview/) > @@ -13,9 +13,9 @@ These Rover commands are _primarily_ for interacting with monolithic graphs that ### `graph fetch` -> This command requires [authenticating Rover with Apollo Studio](../configuring/#authenticating-with-apollo-studio). +> This command requires [authenticating Rover with GraphOS](../configuring/#authenticating-with-graphos). -You can use Rover to fetch the current schema of any Studio graph and variant it has access to. +You can use Rover to fetch the current schema of any GraphOS graph and variant it has access to. Run the `graph fetch` command, like so: @@ -68,13 +68,13 @@ rover graph fetch my-graph@my-variant --output prod-schema.graphql > For more on passing values via `stdout`, see [Conventions](../conventions#using-stdout). -## Publishing a schema to Apollo Studio +## Publishing a schema to GraphOS ### `graph publish` -> This command requires [authenticating Rover with Apollo Studio](../configuring/#authenticating-with-apollo-studio). +> This command requires [authenticating Rover with GraphOS](../configuring/#authenticating-with-graphos). -You can use Rover to publish schema changes to one of your [Apollo Studio graphs](/studio/org/graphs/). +You can use Rover to publish schema changes to one of your [GraphOS monographs](/studio/org/graphs/#monographs). Use the `graph publish` command, like so: @@ -82,11 +82,9 @@ Use the `graph publish` command, like so: rover graph publish my-graph@my-variant --schema ./schema.graphql ``` -The argument `my-graph@my-variant` in the example above specifies the ID of the Studio graph you're publishing to, along with which [variant](/studio/org/graphs/#variants) you're publishing to. +The argument `my-graph@my-variant` in the example above specifies the ID of the GraphOS graph you're publishing to, along with which [variant](/studio/org/graphs/#variants) you're publishing to. -> You can omit `@` and the variant name. If you do, Rover publishes the schema to the default variant, named `current`. - -If the graph exists in the graph registry, but the variant does not, a new variant will be created on publish. +If the graph exists in GraphOS but the _variant_ doesn't, a new variant is be created on publish. ### Providing the schema @@ -106,7 +104,7 @@ Whenever possible, we recommend publishing a `.graphql` file directly instead of ### `graph check` -Before you [publish schema changes to Apollo Studio](#publishing-a-schema-to-apollo-studio), you can [check those changes](/graphos/delivery/schema-checks/) to confirm that you aren't introducing breaking changes to your application clients. +Before you [publish schema changes to GraphOS](#publishing-a-schema-to-graphos), you can [check those changes](/graphos/delivery/schema-checks/) to confirm that you aren't introducing breaking changes to your application clients. To do so, you can run the `graph check` command: @@ -126,13 +124,13 @@ If you don't want to wait for the check to complete, you can run the command wit #### Running checks in CI -If you're running schema checks in CI, you might want to pass the `--background` flag to `rover graph check`. This flag instructs Rover to initiate schema checks but _not_ await their result. If you've [connected Apollo Studio to your GitHub repository](/graphos/delivery/github-integration/), the integration detects the checks execution and adds a status to the associated pull request. +If you're running schema checks in CI, you might want to pass the `--background` flag to `rover graph check`. This flag instructs Rover to initiate schema checks but _not_ await their result. If you've [connected GraphOS to your GitHub repository](/graphos/delivery/github-integration/), the integration detects the checks execution and adds a status to the associated pull request. ## Deleting a variant ### `graph delete` -> This command requires [authenticating Rover with Apollo Studio](../configuring/#authenticating-with-apollo-studio). +> This command requires [authenticating Rover with GraphOS](../configuring/#authenticating-with-graphos). You can delete a single variant of a graph by running `rover graph delete`: diff --git a/docs/source/commands/readmes.mdx b/docs/source/commands/readmes.mdx index fb8af6583..1b915da89 100644 --- a/docs/source/commands/readmes.mdx +++ b/docs/source/commands/readmes.mdx @@ -3,15 +3,15 @@ title: Rover README commands description: Publish and retrieve your graph variant's README --- -These Rover commands enable you to publish and fetch the [README](/studio/studio-graph-features/#the-readme-page) associated with a particular graph variant. +These Rover commands enable you to publish and fetch the [README](/graphos/graphs/studio-features/#the-readme-page) associated with a particular graph variant. -READMEs are [Markdown-based](/studio/studio-graph-features/#supported-markdown) and support Apollo-specific shortcodes, which are documented [here](/studio/studio-graph-features/#readme-shortcodes). +READMEs are [Markdown-based](/graphos/graphs/studio-features/#supported-markdown) and support Apollo-specific shortcodes, which are documented [here](/graphos/graphs/studio-features/#readme-shortcodes). -## Fetching a README from Apollo Studio +## Fetching a README from GraphOS ### `readme fetch` -> This command requires [authenticating Rover with Apollo Studio](../configuring/#authenticating-with-apollo-studio). +> This command requires [authenticating Rover with GraphOS](../configuring/#authenticating-with-graphos). You can use Rover to fetch the README of any Studio graph variant you have access to. @@ -40,13 +40,13 @@ rover readme fetch my-graph@my-variant --format json > For more on passing values via `stdout`, see [Conventions](../conventions#using-stdout). -## Publishing a README to Apollo Studio +## Publishing a README to GraphOS ### `readme publish` -> This command requires [authenticating Rover with Apollo Studio](../configuring/#authenticating-with-apollo-studio). +> This command requires [authenticating Rover with GraphOS](../configuring/#authenticating-with-graphos). -You can use Rover to publish a README to one of your [Apollo Studio graphs](/studio/org/graphs/). +You can use Rover to publish a README to one of your [GraphOS graphs](/graphos/graphs/overview/). Use the `readme publish` command, like so: diff --git a/docs/source/commands/subgraphs.mdx b/docs/source/commands/subgraphs.mdx index 6e9fd2adf..94589a3b0 100644 --- a/docs/source/commands/subgraphs.mdx +++ b/docs/source/commands/subgraphs.mdx @@ -1,6 +1,5 @@ --- title: Rover subgraph commands -description: For use with Apollo Federation --- A **subgraph** is a graph that contributes to the composition of a federated **supergraph**: @@ -18,11 +17,11 @@ Rover commands that interact with subgraphs begin with `rover subgraph`. ## Fetching a subgraph schema -These commands enable you to fetch the schema for a single subgraph in a federated graph. To instead fetch the API schema for a supergraph, use [`rover graph fetch`](./graphs#graph-fetch). To fetch the supergraph schema, use [`rover supergraph fetch`](./supergraphs#supergraph-fetch). +These commands enable you to fetch the schema for a single subgraph in a supergraph. To instead fetch the API schema for a supergraph, use [`rover graph fetch`](./graphs#graph-fetch). To fetch the supergraph schema, use [`rover supergraph fetch`](./supergraphs#supergraph-fetch). ### `subgraph fetch` -> This command requires [authenticating Rover with Apollo Studio](../configuring/#authenticating-with-apollo-studio). +> This command requires [authenticating Rover with GraphOS](../configuring/#authenticating-with-graphos). You can use Rover to fetch the current schema of any subgraph that belongs to a Studio graph and variant that Rover has access to. @@ -34,9 +33,7 @@ rover subgraph fetch my-graph@my-variant --name accounts The argument `my-graph@my-variant` in the example above is a [graph ref](../conventions/#graph-refs) that specifies the ID of the Studio graph you're fetching from, along with which [variant](/graphos/graphs/overview/#variants) you're fetching. -> You can omit `@` and the variant name. If you do, Rover uses the default variant, named `current`. - -**The `--name` option is required.** It specifies which subgraph you're fetching the schema for. +**The `--name` option is required.** It specifies _which_ subgraph you're fetching the schema for. ### `subgraph introspect` @@ -92,9 +89,9 @@ rover subgraph introspect http://localhost:4000 --output accounts-schema.graphql ### `subgraph list` -> This command requires [authenticating Rover with Apollo Studio](../configuring/#authenticating-with-apollo-studio). +> This command requires [authenticating Rover with GraphOS](../configuring/#authenticating-with-graphos). -You can use the `subgraph list` to list all of a particular supergraph's available subgraphs in Apollo Studio: +You can use the `subgraph list` to list all of a particular supergraph's available subgraphs in GraphOS: ```bash rover subgraph list my-supergraph@staging @@ -120,11 +117,11 @@ Subgraphs: View full details at https://studio.apollographql.com/graph/my-supergraph/service-list ``` -## Publishing a subgraph schema to Apollo Studio +## Publishing a subgraph schema to GraphOS ### `subgraph publish` -> This command requires [authenticating Rover with Apollo Studio](../configuring/#authenticating-with-apollo-studio). +> This command requires [authenticating Rover with GraphOS](../configuring/#authenticating-with-graphos). You can use Rover to publish schema changes to a subgraph in one of your GraphOS-managed [supergraphs](/graphos/graphs/overview/). @@ -137,7 +134,7 @@ rover subgraph publish my-supergraph@my-variant \ --routing-url "https://my-running-subgraph.com/api" ``` -The argument `my-supergraph@my-variant` in the example above is a [graph ref](../conventions/#graph-refs) that specifies the ID of the Studio graph you're publishing to, along with which [variant](/graphos/graphs/overview/#variants) you're publishing to. +The argument `my-supergraph@my-variant` in the example above is a [graph ref](../conventions/#graph-refs) that specifies the ID of the GraphOS graph you're publishing to, along with which [variant](/graphos/graphs/overview/#variants) you're publishing to. > You can omit `@` and the variant name. If you do, Rover publishes the schema to the default variant, named `current`. @@ -229,9 +226,9 @@ This option has no effect if you publish to a non-monolithic variant. ### `subgraph check` -> This command requires [authenticating Rover with Apollo Studio](../configuring/#authenticating-with-apollo-studio). +> This command requires [authenticating Rover with GraphOS](../configuring/#authenticating-with-graphos). -Before you [publish subgraph schema changes to Apollo Studio](#publishing-a-subgraph-schema-to-apollo-studio), you can [check those changes](/graphos/delivery/schema-checks/) to confirm that you aren't introducing breaking changes to your application clients. +Before you [publish subgraph schema changes to GraphOS](#publishing-a-subgraph-schema-to-graphos), you can [check those changes](/graphos/delivery/schema-checks/) to confirm that you aren't introducing breaking changes to your application clients. To do so, you can run the `subgraph check` command: @@ -260,7 +257,7 @@ If you're running schema checks in CI, you might want to pass the `--background` ### `subgraph delete` -> This command requires [authenticating Rover with Apollo Studio](../configuring/#authenticating-with-apollo-studio). +> This command requires [authenticating Rover with GraphOS](../configuring/#authenticating-with-graphos). You can delete a single subgraph from a federated variant by running `rover subgraph delete`: diff --git a/docs/source/commands/supergraphs.mdx b/docs/source/commands/supergraphs.mdx index 39cfbe56e..788c0c531 100644 --- a/docs/source/commands/supergraphs.mdx +++ b/docs/source/commands/supergraphs.mdx @@ -16,11 +16,11 @@ graph BT; Rover commands that interact with supergraphs begin with `rover supergraph`. These commands primarily deal with [supergraph schemas](/federation/federated-types/overview/). -## Fetching a supergraph schema from Apollo Studio +## Fetching a supergraph schema from GraphOS ### `supergraph fetch` -> This command requires [authenticating Rover with Apollo Studio](../configuring/#authenticating-with-apollo-studio). +> This command requires [authenticating Rover with GraphOS](../configuring/#authenticating-with-graphos). You can use Rover to fetch the supergraph schema of any federated Studio graph variant it has access to. Run the `supergraph fetch` command, like so: @@ -95,6 +95,7 @@ subgraphs: graphref: mygraph@current subgraph: actors ``` + ### Output format By default, `rover supergraph compose` outputs a [supergraph schema](/federation/federated-types/overview/) document to `stdout`. You provide this artifact to [`@apollo/gateway`](/federation/api/apollo-gateway/) or the [🦀 Apollo Router](/router/) on startup. diff --git a/docs/source/configuring.md b/docs/source/configuring.md index 22957cd0c..e0d03ee72 100644 --- a/docs/source/configuring.md +++ b/docs/source/configuring.md @@ -2,16 +2,16 @@ title: Configuring Rover --- -## Authenticating with Apollo Studio +## Authenticating with GraphOS ### 1. Obtain an API key -All Rover commands that communicate with [Apollo Studio](/studio/) require an API key to do so. Studio supports two types of API keys: **personal API keys** and **graph API keys**. +All Rover commands that communicate with [GraphOS](/graphos/) require an API key to do so. GraphOS supports two types of API keys: **personal API keys** and **graph API keys**. * **On your local development machine,** use a personal API key. * **In shared environments like CI,** use a graph API key. -> [Learn how to obtain an API key](/graphos/api-keys/) +> [Learn how to obtain an API key.](/graphos/api-keys/) ### 2. Provide the API key to Rover @@ -87,7 +87,7 @@ Every Rover command supports two options for configuring its output behavior: ### JSON output -> **Note:** The `--format` option was added in Rover v0.11.0. Earlier versions of Rover use the `--output` option to set output format. +> **Note:** The `--format` option was added in Rover `v0.11.0`. Earlier versions of Rover use the `--output` option to set output format. > > Current versions of Rover still support using `--output` this way, but that support is deprecated and will be removed in a future release. @@ -251,7 +251,7 @@ rover supergraph compose --output ./supergraph-schema.graphql --config ./supergr If the specified file already exists, Rover overwrites it. -> **Note:** This functionality is available in Rover v0.11.0 and later. In _earlier_ versions of Rover, the `--output` option instead provides the functionality that's now provided by the [`--format` option](#json-output). +> **Note:** This functionality is available in Rover `v0.11.0` and later. In _earlier_ versions of Rover, the `--output` option instead provides the functionality that's now provided by the [`--format` option](#json-output). > > Current versions of Rover still support using `--output` like `--format`, but that support is deprecated and will be removed in a future release. @@ -268,7 +268,7 @@ APOLLO_CONFIG_HOME=./myspecialconfig/ ## Git context -Rover sends non-confidential information about your Git environment to Apollo Studio when you run a `check` or `publish` command. This information is displayed in relevant views of the Studio UI, making it easier to track down where schema changes were proposed or published: +Rover sends non-confidential information about your Git environment to GraphOS when you run a `check` or `publish` command. This information is displayed in relevant views of the Studio UI, making it easier to track down where schema changes were proposed or published: Checks info in Apollo Studio @@ -300,7 +300,7 @@ Currently, only Git is fully supported by Apollo Studio. In some configurations (especially in internal networks), you might need Rover to communicate over encrypted channels (e.g., HTTPS) while avoiding strict digital certificate verifications that validate hostnames. You might even need to bypass digital certificate validation entirely. -**This is generally not recommended and considered much less secure.** However, for cases where it's necessary, you can use the following flags to configure how Rover validates HTTPS requests: +**This is not recommended and considered much less secure!** However, for cases where it's necessary, you can use the following flags to configure how Rover validates HTTPS requests: - The `--insecure-accept-invalid-hostnames` flag disables hostname validation. If hostname verification is not used, any valid certificate for any site is trusted for use from any other. This introduces a significant vulnerability to person-in-the-middle attacks. diff --git a/docs/source/conventions.md b/docs/source/conventions.md index 375a6cf8a..766db0cf1 100644 --- a/docs/source/conventions.md +++ b/docs/source/conventions.md @@ -10,7 +10,7 @@ These are conventions for all Rover commands. Rover provides commands for interacting with federated [`subgraph`s](./commands/subgraphs/) and [`supergraph`s](./commands/supergraphs/), along with commands for interacting with a monolithic (non-federated) [`graph`](./commands/graphs/). - A **supergraph** is the composition of multiple **subgraphs** in a [federated architecture](/federation/): +A **supergraph** is the composition of multiple **subgraphs** in a [federated architecture](/federation/): ```mermaid graph BT; @@ -33,7 +33,7 @@ graph_id@variant_name **For example:** `docs-example-graph@staging` -All Rover commands that interact with the Apollo graph registry require a graph ref as their first positional argument. If you're using the default variant (`current`), you don't need to include the `@variant_name` portion of the graph ref (although it's recommended for clarity). +All Rover commands that interact with GraphOS require a graph ref as their first positional argument. ## I/O diff --git a/docs/source/getting-started.md b/docs/source/getting-started.md index ed60a8459..75767326d 100644 --- a/docs/source/getting-started.md +++ b/docs/source/getting-started.md @@ -23,7 +23,7 @@ curl -sSL https://rover.apollo.dev/nix/v0.13.0 | sh If your machine doesn't have the `curl` command, you can get the latest version from the [`curl` downloads page](https://curl.se/download.html). -> Note: `rover supergraph compose` is currently not available for Alpine Linux. You can track the progress for supporting this command on Alpine in [this issue](https://github.com/apollographql/rover/issues/537). +> **Note:** The `rover supergraph compose` command is not yet available for Alpine Linux. You can track the progress for supporting this command on Alpine in [this issue](https://github.com/apollographql/rover/issues/537). ### Windows PowerShell installer diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 0ce2945a0..6ce29a1ce 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -3,24 +3,22 @@ title: The Rover CLI description: Overview --- -**Rover** is Apollo's command-line interface for managing and maintaining graphs with [GraphOS](/graphos/): +**Rover** is the command-line interface for managing and maintaining graphs with [Apollo GraphOS](/graphos/). -```shell title="Examples" -# Compose multiple GraphQL APIs -$ rover dev +```shell title="Example commands" +# Publish a subgraph schema to GraphOS +$ rover subgraph publish my-graph@my-variant --name my-subgraph --schema ./schema.graphql -# Publish your graph's schema to Apollo -$ rover graph publish my-graph@my-variant --schema ./schema.graphql +# Run your supergraph router locally and add multiple subgraphs +$ rover dev -# Fetch your GraphQL server's schema via introspection +# Fetch a GraphQL server's schema via introspection $ rover graph introspect http://localhost:4000/graphql # Compose a federated supergraph schema from multiple subgraphs $ rover supergraph compose --config ./supergraph.yaml ``` -Rover helps you safely publish and fetch GraphQL schemas (both [federated](./commands/subgraphs/) and [monolithic](./commands/graphs/)) from the Apollo schema registry. -