Get started with GraphOS

Hello! 👋 This quickstart gets you up and running with GraphOS and your first supergraph. None of this setup requires a paid plan.

To complete these steps, it's helpful to have one of the following available:

• The URL of your running GraphQL server, with introspection enabled
• Your GraphQL server's schema, as plaintext SDL

If you don't have either, that's okay! You can still try out GraphOS with an example GraphQL server. To do so, provide all values labeled 🚀 Example setup in the steps below.

1. Create your Apollo account

If you already have an Apollo account, and you created your organization prior to October 2022, you might need to create a new organization to create cloud supergraphs:

Some legacy organizations can upgrade to a current plan. See details.

Apollo Studio is the primary web interface for interacting with the GraphOS platform. We'll use Studio in every step of this tutorial, starting with creating an account.

1. Go to studio.apollographql.com and click Let's get started.

2. Choose a signup method (GitHub or username/password).

   Studio then shows a signup form (its details vary depending on your signup method):

   

3. Complete the signup form.

   • If you want to customize your organization's details (such as its name or ID), you can uncheck Create an organization for my automatically.

4. Click Create Account.

You're all set! Studio automatically redirects you to your newly created organization, which is on the Serverless (Free) plan by default.

2. Create your first supergraph

You now have an Apollo Studio organization, but it doesn't contain any graphs yet. Let's create your first cloud supergraph, which will incorporate your existing GraphQL API.

1. From your new organization in Apollo Studio, navigate to the Graphs tab if it isn't already open.

   Because you haven't created any graphs yet, Studio shows the following:

   

2. Click Connect your GraphQL API. The following dialog appears:

   

3. Provide your GraphQL API's Endpoint URL.

   • This is the same URL that client applications currently use to query your API.
   • 🚀 Example setup: https://flyby-locations-sub.herokuapp.com/

   After you provide the URL, Studio attempts to fetch your API's schema from it via introspection. The result of that fetch is shown beneath the text box:

   

4. If the schema fetch failed, click Advanced options (otherwise, proceed to the next step):

   
   • If your GraphQL server requires certain HTTP headers for Studio to introspect it, click Provide HTTP Headers to specify them.
   • Otherwise, click Upload your schema directly to provide your API's schema as plaintext SDL.

5. Provide a Subgraph Name for your API. This name uniquely identifies your API among any other APIs you might add to the supergraph later.

   • The name should reflect the data or capabilities that your API provides.
   • 🚀 Example setup: locations

6. Click Next.

   • If the Next button is inactive, Studio hasn't obtained your API's schema! Make sure to provide it using one of the methods described in the previous few steps.

   The following dialog appears:

   

7. Provide an ID and a name for your new supergraph.

   • The ID is immutable and must be unique across all of Apollo. You'll use this value to reference your supergraph from various tools, such as the Rover CLI.
   • The name is displayed throughout Studio and helps your team distinguish between your different graphs. You can change your supergraph's name at any time.

8. Click Create Supergraph.

Nice work! You've created your first cloud supergraph, which is now listed in your organization's Graphs tab:

Your GraphQL API is now the first subgraph in a cloud supergraph. Later, we'll cover how to add another subgraph.

3. Learn about your variant

When you created your supergraph, you also created its first variant (which is named main). Every graph in GraphOS has one or more variants. Each variant represents a different environment where the graph runs (such as staging or production).

Let's look at the helpful views that Studio provides for your variant!

From your Graphs tab, click your graph's main variant. This opens the variant's README page.

The README is great for documenting your supergraph so team members can learn the basics of how to work with it. It supports Markdown syntax like a typical README in a Git repository.

While you're viewing any page for a variant, the following navigation is shown on the left side:

We'll cover some of these pages in later steps, but feel free to click around and see what each provides! You can also expand the summary table below:

Variant pages in Studio

4. Configure your router's network settings

Before we try executing operations on your supergraph, we need to make sure your router is set up to communicate successfully with both your clients and your subgraph.

Go to your variant's Settings page, then click Cloud Router:

This page displays your router's endpoint URL, and it also enables you to customize its networking behavior with YAML-based config. In the Router configuration YAML section, you'll see a default configuration similar to the following:

1
cors:
2
  origins:
3
    - https://studio.apollographql.com
4
headers:
5
  subgraphs:
6
    locations: # This value matches your subgraph's name.
7
      request:
8
        - propagate:
9
            matching: '.*'

Let's modify this default config to work with your clients and your subgraph.

CORS rules

The Cross-Origin Resource Sharing (CORS) protocol enables a server to dictate exactly which origins can communicate with it from a web browser.

As shown in the configuration above, by default your router only accepts browser-based requests from Apollo Studio! If other browser-based applications will query your supergraph, you need to modify your CORS settings.

To limit browser-based queries to specific domains, list those domains in the configuration YAML like so:

1
cors:
2
  origins:
3
    - https://studio.apollographql.com
4
    - https://first-domain.example.com
5
    - https://second-domain.example.com

To allow browser-based queries from any domain, you can instead set allow_any_origin: true:

1
cors:
2
  allow_any_origin: true

Header rules

If your subgraph's server requires certain HTTP headers to communicate with it (such as an Authorization header), let's specify those headers in the configuration YAML.

Creating secrets

If the value of any required header includes a secure credential (such as an access token), let's first create a router-specific secret for that credential.

On the Cloud Router page, click Save a secret. The following dialog appears:

Enter a name and value for your secret. You can't view a secret's value after you save it, so make sure that the value is correct before saving. When you're ready, click Save secret.

Your secret is encrypted and stored. Now you can use the secret's value in your router's configuration YAML.

Setting header values

In your configuration YAML, you set header values to pass from your router to your subgraph like so:

1
headers:
2
  subgraphs:
3
    locations: # This value matches your subgraph's name.
4
      request:
5
        - propagate:
6
            matching: '.*'
7
        - insert:
8
            name: 'Authorization'
9
            value: 'Bearer ${env.MY_SECRET}'
10
        - insert:
11
            name: 'X-CUSTOM-HEADER'
12
            value: 'Custom value'

Here, we add two headers: Authorization and X-CUSTOM-HEADER. The Authorization header's value includes the value of a router-specific secret named MY_SECRET.

5. Query your supergraph

Let's try executing a query against your new supergraph! To do that, we'll use one of Studio's most powerful features: the Explorer. The Explorer is a GraphQL IDE that provides visibility into your supergraph's entire schema and helps you build and run queries against it.

From your organization's Graphs tab, select your new variant and then open its Explorer page from the left navigation. The Explorer looks like this:

Try building a couple of queries and running them against your supergraph. Notice that the supergraph supports the exact same query structures as your underlying GraphQL API.

Because you've created a cloud supergraph, operations you run in the Explorer are sent to the GraphOS-managed router that sits in front of your API. Application clients will also query the router instead of querying your API directly.

If the Explorer returns errors for all operations, GraphOS might not be finished provisioning your router. If this is the case, an INITIATING ENDPOINT label is shown at the top of the page:

6. View operation metrics

Here's a powerful benefit of a cloud supergraph: because clients execute operations against your GraphOS-managed router, the router automatically collects metrics on those operations! You can then visualize those metrics in Studio.

Go to your variant's Operations page, which looks like this:

The operations you executed in the Explorer should already be represented on this page! After you update all of your clients to query your router, the Operations page becomes vital to monitoring your supergraph's performance.

7. Connect clients to your router

Your supergraph is ready to start receiving client operations! If you have existing client applications that connect directly to your GraphQL API, you can update their GraphQL endpoint URL to your router's URL.

Similarly, any new client applications should use your router's URL.

Your router's URL is available from the top of your variant's README page:

Every router URL is on a subdomain of apollographos.net.

Next steps

Congratulations! 🎉 You've built your first cloud supergraph on GraphOS. Next, we'll cover some of the most common and important actions to perform on your supergraph, including:

• Updating your subgraph's schema
• Adding another subgraph
• Setting up schema checks

Go to next steps.