Docs
Launch GraphOS Studio

Get started with GraphOS

Create your first cloud supergraph


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 , with enabled
  • Your 's schema, as plaintext

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

β“˜ NOTE

If you're getting started with a , follow this quickstart instead.

1. Create your Apollo account

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

β“˜ NOTE

If you already have an Apollo account, you can skip to creating your first supergraph. If your account is part of an organization created prior to October 2022, you might need to create a new organization to create cloud :

Studio organization list

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

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

  2. Choose a signup methodβ€”either using GitHub or with an email and password.

    Studio then shows a signup form. Its details vary depending on your signup method:

    Studio signup form
  3. Complete the form, and click Create Account. By default, your account is on the Serverless (Free) plan.

2. Create your first supergraph

You now have a account, but it doesn't contain any graphs yet. The next steps guide you to create a cloud supergraph. A cloud automatically provisions a -managed router in front of your API. Clients your instead of querying your API directly.

With this architecture, you can combine multiple APIs into a single , all orchestrated by the :

Your infrastructure
GraphOS
Your GraphQL API
Second API
Third API
Router
Clients

If you're creating a new cloud from an existing account, follow the steps in that section. Otherwise, continue with the steps below.

From a new account

  1. Studio prompts you to Connect your API or Try a demo graph. If you have the URL of your running , select Connect API. Otherwise, you can select Try a demo graph, and Apollo creates a demo for you to play with.

    Studio signup form
  2. Provide your GraphQL API's Endpoint URL. This is the same URL that client applications currently use to your API. After you provide the URL, Studio attempts to fetch your API's schema from it via . The result of that fetch is shown beneath the text box:

    Displayed result of API schema fetch
    • If your requires certain HTTP headers for Studio to introspect it, click Provide HTTP Headers to specify them.
  3. Provide the name of your service. The name should reflect the data or capabilities that your API provides and should uniquely identify your API among any other APIs you might add to the later.

    β“˜ NOTE

    The service name is immutable.

  4. Click Continue.

    • If the Continue button is inactive, Studio hasn't obtained your API's schema. If necessary you can bypass by uploading your schema. By selecting this option, you can manually copying and pasting your schema, or dragging and dropping a .gql or .graphql file.
  5. Provide a name and ID for your new .

    Entering a name and id
    • The name is displayed throughout Studio and helps your team distinguish between your different . You can change your graph's name at any time.
    • The ID is immutable and must be unique across all of Apollo. Make sure it starts with a letter and contains only letters, numbers, and dashes. You'll use the ID to reference your from various tools, such as the .
  6. Click Continue.

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

An organization's list of cloud supergraphs

Your API is now the first subgraph in that cloud . Skip to the next step to learn about variants.

From an existing account

  1. From your account in GraphOS Studio, navigate to the Graphs tab if it isn't already open. Select + Create New Graph in the top right.
An organization's list of cloud supergraphs
  1. Click Connect your GraphQL API. The following dialog appears:

    Supergraph creation dialog
  2. Provide your API's Endpoint URL.

    • This is the same URL that client applications currently use to your API.
    • If you don't have a URL, you can use https://flyby-locations-sub.herokuapp.com/ as an example.

    After you provide the URL, Studio attempts to fetch your API's schema from it via . Once the fetch succeeds, the input shows a green check.

    Displayed result of API schema fetch
  3. (Optional) You can click Advanced options for the following scenarios:

  • If your requires certain HTTP headers for Studio to introspect it, click Provide HTTP Headers to specify them.
  • You can click Provide your schema directly to provide your API's schema as plaintext .
  • Finally, you can select Use local introspection to provide a local URL and do a one-time of your schema.
  1. Provide a Subgraph Name for your API. This name uniquely identifies your API among any other APIs you might add to the later. The name should reflect the data or capabilities that your API provides.

    • If you're using the https://flyby-locations-sub.herokuapp.com/ example URL, you can enter Locations as the name.

    β“˜ NOTE

    A name is immutable.

  2. 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 steps 3 and 4.

    The following dialog appears:

    Setting a name and ID for a new supergraph
  3. Provide a name and ID for your new .

    • The name is displayed throughout Studio and helps your team distinguish between your different . You can change your graph's name at any time.
    • The ID is immutable and must be unique across all of Apollo. Make sure it starts with a letter and contains only letters, numbers, and dashes. You'll use the ID to reference your from various tools, such as the .
  4. Click Create Supergraph.

You've now created your first cloud , and you can view it listed in your organization's Graphs tab:

An organization's list of cloud supergraphs

Your API is now the first subgraph in that cloud .

3. Learn about your variant

When you created your , you also created its first variant. Every in has one or more representing a different environment where the graph runs, such as staging or production. Each variant has a name that you set or is current by default.

Let's look at the views that Studio provides to help you understand your :

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

The README is great for your 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 , the following navigation is shown on the left side:

List of pages for a graph variant in Studio

You can collapse this navigation to show only icons.

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 on your , we need to make sure your is set up to communicate successfully with both your clients and your .

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

Configuring the routing for your cloud supergraph in GraphOS Studio

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

cors:
origins:
- https://studio.apollographql.com
headers:
subgraphs:
locations: # This value matches your subgraph's name.
request:
- propagate:
matching: '.*'

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

β“˜ NOTE

Make sure to save any changes you make to your configuration YAML in Studio.

CORS rules

β“˜ NOTE

If no browser-based will communicate with your , you can skip this section.

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 only accepts browser-based requests from ! If other browser-based applications will your , you need to modify your CORS settings.

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

cors:
origins:
- https://studio.apollographql.com
- https://first-domain.example.com
- https://second-domain.example.com

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

cors:
allow_any_origin: true

πŸ’‘ TIP

For advanced CORS options, see Configuring cloud routing.

Header rules

β“˜ NOTE

If your doesn't need to provide specific HTTP headers in its requests to your , you can skip this section.

If your '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:

Adding a secret to your router

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 's configuration YAML.

Setting header values

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

headers:
subgraphs:
locations: # This value matches your subgraph's name.
request:
- propagate:
matching: '.*'
- insert:
name: 'Authorization'
value: 'Bearer ${env.MY_SECRET}'
- insert:
name: 'X-CUSTOM-HEADER'
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.

β“˜ NOTE

Make sure you save any router-specific secrets before you update your config YAML to include them. Otherwise, your won't be updated with the new configuration.

5. Query your supergraph

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

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

The default Explorer view for a new supergraph

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

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

β“˜ NOTE

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

Label in Studio indicating a router hasn't finished provisioning

6. View operation and field metrics

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

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

The Insights page in GraphOS Studio, showing metrics for operations and their fields

The you executed in the Explorer should already be represented on this page. After you update all your clients to your , the Insights page becomes vital to monitoring your 's performance.

Learn more about the available metrics in the metrics documentation.

7. Connect clients to your router

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

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

β“˜ NOTE

  • For all browser-based clients, make sure their origin is allowed in your 's CORS rules.

  • Only update clients that communicate with the correct instance of your API. For example, if your API has staging and production instances, only update clients that communicate with the instance used by this .

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

Router URL shown on the README page

Every 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 's schema
  • Adding another
  • Setting up

Go to next steps.

Previous
API keys
Next
Self-hosted setup
Edit on GitHubEditForumsDiscord

Β© 2024 Apollo Graph Inc.

Privacy Policy

Company