Apollo Connectors Quickstart

Integrate REST APIs into your graph

⏱️ Estimated time: 10 minutes

Hello! 👋 By completing this tutorial, you'll transform data from a fictional REST API into a GraphQL API that lets clients request exactly what they need.

If you completed the Apollo GraphOS quickstart and already have a graph initiated with rover init using the example ecommerce REST API, you can skip to Step 2: Add new fields.

tip
If you learn best with videos and exercises, this interactive course teaches you how to integrate REST APIs into a graph. Prefer to start with a high-level conceptual understanding? Check out the Why Use Connectors?.

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 add and transform more data from the /products endpoint.

Step 2. Add new fields

To expose additional data through your graph, 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.

    Notice the selection mapping:

    GraphQL
    products.graphql
    type Query {
  products: [Product]
    @connect(
      source: "ecomm"
      http: { GET: "/products" } # GET, POST, PUT, PATCH, DELETE.
      selection: """
      $.products {
        id
        name
        description
      }
      """
    )
}

    This is the part you'll update next.

  2. The best way to simultaneously explore what data an endpoint offers and update your Connector accordingly is with the Connectors Mapping Playground. This link is prepopulated with data from the /products endpoint and embedded below:

Connectors Mapping Playground
Best viewed on a larger screen

  1. Try adding slug to the selection mapping Mapping panel.

    GraphQL
    $.products {
    id
    name
    description
    slug
}

    Notice the products in the Results panel now include slugs.

  2. Imagine you also want your graph to expose a new field called primaryTag. This field should return the name of the first tag in a product's tags array. Using the ->first method, play with the Mapping panel until you've achieved this.

    Check your selection mapping
    GraphQL
    Mapping
    $.products {
  id
  name
  description
  slug
  primaryTag: tags->first.name
}

  3. Update your products.graphql:

    • Add slug and primaryTag fields to your Product type.

    • Copy and paste the mapping you've finessed in the Mapping Playground into the selection field of your Connector.

    • Save your products.graphql.

    Check your Connector
    GraphQL
    products.graphql
    type Product {
  id: ID!
  name: String
  description: String
  slug: String
  primaryTag: String
}

type Query {
  products: [Product]
    @connect(
      source: "ecomm"
      http: { GET: "/products" }
      selection: """
      $.products {
        id
        name
        description
        slug
        primaryTag: tags->first.name
      }
      """
    )
}

  4. To test the updated schema as expected, run the following query in your Sandbox, which should still be running on http://localhost:4000.

    GraphQL
    Sandbox request
    query products {
  products {
    name
    slug
    primaryTag
  }
}

You should see the new fields you mapped from the /products endpoint. Congrats—you've integrated more data into your graph!

Next steps
Feedback

Ask Community
OSZAR »