Connect REST APIs

This guide walks through a test use case for building, developing, and managing a GraphQL API with Apollo and Apollo Connectors for REST APIs.

Prerequisites

• Set up a GraphOS organization and member account

By the end of the milestone, you'll have:

• Installed the Rover CLI

• A Connectors-powered graph with a test use case running locally

• Sent an operation to your local GraphQL endpoint

Before you start

Rover is Apollo's official CLI for managing graphs and subgraphs. It's the main tool for setup, development, publishing schemas, and more.

Install and authenticate Rover by following the Rover CLI Getting Started guide.

Steps to complete

Identify data sources

Identify the REST API data sources you need to use in your first use case.

Review the REST API requirements and limitations of Connectors to ensure your data sources are suitable.

Initialize the local project

1. Create a new directory for your project.

2. Run rover init in a terminal window to start the setup wizard.

3. Select Create a new graph and then Start a graph with one or more REST APIs when prompted.

4. Enter a name for your graph and proceed with the wizard to generate the required files.

Store graph credentials

Copy the APOLLO_GRAPH_REF and APOLLO_KEY from the rover init output and paste into a .env file:

1# .env
2# (Formatted graph-id@variant, references a graph in the Apollo GraphOS platform)
3APOLLO_GRAPH_REF=
4
5# (This is your graph's API key)
6APOLLO_KEY=

You need these credentials to start the local dev server, even for local-only work.

Define your GraphQL schema with Connectors

Create .graphql schema files using Connectors.

Refer to the Connectors documentation to learn more about the directives you need to map REST endpoints to GraphQL fields.

Configure supergraph composition

The supergraph.yaml file tells Rover how to compose your local graph. Update it to reference your schema files.

1subgraphs:
2  products:
3    routing_url: http://ignore
4    schema:
5      file: path/to/your-products-schema.graphql
6  reviews:
7    routing_url: http://ignore
8    schema:
9      file: path/to/your-reviews-schema.graphql
10federation_version: =2.11.0

(Optional) Configure router settings

If you need special settings such as CORS, authentication, and header passthrough, create a router-config.yaml and reference it with --router-config when starting Rover.

1headers:
2  all:
3    request:
4      - propagate:
5          matching: ^*
6cors:
7  allow_any_origin: true
8
9connectors:
10  sources:
11    # myconnector references the connector name defined in the supergraph.yaml
12    # v1 is the name of the source in the @source directive
13    myconnector.v1:
14      $config:
15        apikey: $MY_SECRET

Start the local development server

Set your environment variables, then run:

1APOLLO_KEY=<YOUR_APOLLO_KEY> \
2APOLLO_GRAPH_REF=<YOUR_APOLLO_GRAPH_REF> \
3rover dev --supergraph-config supergraph.yaml # --router-config router.yaml (optional)

This command launches the router locally, composing your schema automatically.

Test and iterate

• Use Apollo Sandbox at http://localhost:4000 or any GraphQL client to issue queries and validate that your Connectors mappings return the expected data. See the Connectors Troubleshooting Guide in case of any issues.

• Adjust schema files and connector configurations as needed. The local router hot-reloads on changes.

• Use the Connectors Mapping Playground to help map REST API responses to GraphQL types.

Resources

• Course: Getting started with Apollo Connectors

• Apollo Connectors Documentation

• Connectors Mapping Playground

• Connectors library