Apollo GraphOS Quickstart

Orchestrate API calls with a graph

⏱️ Estimated time: 15 minutes

Welcome! 👋 By completing the tutorial, you'll build a fully functional graph that:

  • Combines multiple REST endpoints from a fictional ecommerce API into a single GraphQL endpoint

  • Handles the orchestration of API calls automatically

  • Can be expanded with additional data sources

Let's get started! 🚀

Prerequisites

To get started, you need:

  • A GraphOS Studio account. Sign up for a Free plan if needed.

  • The latest version of the Rover CLI. Install or update it like so:

    terminal
    curl -sSL https://rover.apollo.dev/nix/latest | sh

  • Authentication for Rover with your Studio account. Set it up like so:

    terminal
    rover config auth

Step 1. Create a graph

This quickstart uses Rover to create a graph with Apollo Connectors—the fastest way to integrate REST APIs. Though this graph uses REST, graphs work with any data source or combination of sources.

  1. In your terminal, create a working directory for your graph:

    terminal
    mkdir my-apollo-graph && cd my-apollo-graph

  2. Initialize your graph:

    terminal
    rover init

  3. Follow the prompts, selecting Create a new graph and one or more REST APIs as your starting point. Store the generated credentials securely, particularly the APOLLO_KEY, as it's a graph API key.

Explore example

The best way to explore the example is to run a test request in Apollo Sandbox, a local GraphQL server. To get it started:

  1. In your terminal, follow the Next steps presented by rover init:

    terminal
    APOLLO_KEY=<key> \
APOLLO_GRAPH_REF=<graph-ref> \
rover dev --supergraph-config supergraph.yaml

    Once rover dev is running, the output in your terminal should end with something like this:

    terminal
    ==> Attempting to start router at http://localhost:4000.
==> Health check exposed at http://127.0.0.1:8088/health
WARN: Connector debugging is enabled, this may expose sensitive information.
==> Your supergraph is running! head to http://localhost:4000 to query your supergraph
    Running into errors?
    • If you receive an Error: Not connected to GraphOS., ensure you've included your APOLLO_KEY and GRAPH REF. See Graph API keys for instructions on how to obtain a new one.
    • If you receive an Error: License not found., it means you need a GraphOS account with a current Free or Enterprise plan. Verify your organization's plan by navigating to GraphOS Studio, clicking on Settings, then selecting the Billing tab. Sign up for a new Free plan if necessary.

    The router is the single entry point to the graph. It lets clients fetch exactly what they need with one request, even across multiple APIs.


    A system architecture diagram showing the router as the central component. On the left side, there are Clients (represented by small icons). The router connects to three API services within a Graph: Products API, Reviews API, and Inventory API.

  2. To make requests to your router, open http://localhost:4000 in your browser.

  3. Copy and paste the following query in the central Operation panel to get all products:

    GraphQL
    Example query
    query Products {
  products {
    id
    name
    description
  }
}

    Run the request by clicking the ▶️ Products button.

    Viewing requests in the Connectors Debuggers in Apollo Sandbox

    Your response should show a list of space-related products.

That's it—a fully functional graph! Next, you'll connect a new endpoint to grow your graph.

Step 2. Add a new endpoint

To display a product detail page with reviews, clients normally have to make a request first to one endpoint for product details and then another endpoint for product reviews. With a graph, clients can make one request, asking for all the information simultaneously. Behind the hood, the graph orchestrates the calls to each endpoint to produce a single response.

To integrate new endpoints, you update the GraphQL schema:

  1. Open the products.graphql file generated by rover init and read the comments to get a brief overview of the file.

  2. Copy and paste these additions to your products.graphql:

    GraphQL
    products.graphql
    type Product {
  id: ID!
  name: String
  description: String
  reviews: [Review]
    @connect(
      source: "ecomm"
      http: { GET: "/products/{$this.id}/reviews" }
      selection: """
      $.reviews {
        id
        rating
        comment
      }
      """
    )
}

type Review {
  id: ID!
  rating: Float
  comment: String
}

    This addition:

    • Adds a new Review type

    • Adds a reviews field to the Product type that returns a list of Review objects.

    • Adds a Connector to the reviews field in the Product type to retrieve the reviews

  3. Run a new query in your Sandbox to get product and review information:

    GraphQL
    Sandbox request
    query ProductsWithRating {
  products {
    name
    reviews {
      rating
    }
  }
}

Wahoo! Your response should now include review ratings. The Sandbox offers additional views in the right panel to help you understand what's happening behind the scenes.

Explore orchestration flow

Click Response and select Query Plan to inspect a visual representation of the steps taken to resolve a request.

Viewing a query plan in Apollo Sandbox

A query plan is created by the query planner—the part of the router that breaks down a request into multiple coordinated calls to various endpoints and services. Despite its name, the query planner handles all types of GraphQL operations—not just queries.

Because the request requires two calls to two endpoints, the query planner automatically sequences API calls (the two Fetch nodes in the diagram) and then combines the results (the Flatten node).

Try modifying your query to request different data fields to see how the query plan changes. When you're finished, stop the development server in your terminal.

Step 3. Publish updates

Publish your updated graph to GraphOS using the rover subgraph publish command:

  1. Copy the following multi-line command. Replace <APOLLO_KEY> and <GRAPH_REF> with the credentials generated from rover init.

    terminal
    APOLLO_KEY=<APOLLO_KEY> \
rover subgraph publish <GRAPH_REF> \
--schema ./products.graphql \
--name products \
--no-url

  2. Paste and run your updated multi-line command. Once the command completes, you'll see the following in your terminal:

    terminal
    The supergraph schema for <GRAPH_REF> was updated,
composed from the updated 'products' subgraph
Monitor your schema delivery progression on studio: <STUDIO_URL>

  3. Go to the <STUDIO_URL> provided to land on your graph's Launches page in GraphOS Studio.

Explore Studio

You can use Studio to help analyze the structure of a graph and determine how best to evolve your schemas. For example, from the Schema page, your team can view a Visualization of the types and relationships in your graph.

Schema Visualization in GraphOS Studio

The visualization tool truly shines as your graph grows, transforming complex webs of types and services into an intuitive, navigable map of your data.

Studio also provides detailed information about your operations usage and performance on the Insights page. You should see the Products and ProductsWithRating queries you ran:

Operation usage metrics and insights in GraphOS Studio

As your application scales, these insights help you optimize performance by highlighting slow-resolving fields, tracking error rates, and identifying opportunities to improve your schema based on usage patterns.

Studio empowers teams of developers with observability, management, and governance features, transforming your graph into a collaborative workspace.

Next steps

Depending on your goals, you have several options for learning more:
Feedback

Ask Community