apollo-connectors

by apollographql

Integrate REST APIs into GraphQL supergraphs using @source and @connect directives. Provides a structured 5-step process: research API structure, implement schema with directives, validate via rover supergraph compose , execute connectors, and test coverage Supports request configuration including headers, body payloads, batching for N+1 patterns, and environment variable injection via $env Handles response mapping with field selection, aliasing, sub-selections for nested data, and entity...

npx skills add https://github.com/apollographql/skills --skill apollo-connectors

Download ZIP GitHub

115

Apollo Connectors Schema Assistant

MCP Tools

If GraphOS MCP Tools are available, use them:

connectors-spec: Fetch the complete Connectors specification before starting any connector work
apollo_docs_search: Search for relevant documentation
apollo_docs_read: Read specific documentation pages by slug

Documentation paths by topic:

Requests: /graphos/connectors/requests/url, /headers, /body, /batching
Responses: /graphos/connectors/responses/fields, /error-handling
Mapping: /graphos/connectors/mapping, /arrays, /enums, /literals
Entities: /graphos/connectors/entities, /patterns

Process

Follow this 5-step process. DO NOT skip any steps.

Step 1: Research

Understand the API being called and the structure of responses
Ask the user for example API responses if not provided
Fetch relevant documentation from MCP tools or reference files
DO NOT write any code until research is complete

Step 2: Implement

Create the schema using the template below
Follow the grammar, methods, and variables in the reference files
Ask clarifying questions if unsure about requirements

Step 3: Validate (Compose)

Run rover supergraph compose --config ./supergraph.yaml
Fix any composition errors before proceeding

Step 4: Execute

Run rover connector run --schema <file> -c "<Type.field>" -v "{}"
Verify the connector executes correctly

Step 5: Test

Create or update test files under /tests/
Run rover connector test
Ensure full test coverage for each connector

Schema Template

# Note to AI Friends: This is an Apollo Connectors schema. You should use your connectors-spec MCP tool if you have it available before editing this file.

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.15")
  @link(url: "https://specs.apollo.dev/connect/v0.3", import: ["@source", "@connect"])

@source(name: "api_name", http: { baseURL: "https://api.example.com" })

type Query {
  example(id: ID!): Example
    @connect(
      source: "api_name"
      http: { GET: "/example/{$args.id}" }
      selection: """
      id
      name
      """
    )
}

type Example {
  id: ID!
  name: String
}

Version requirements

Use the latest Long-Term Support (LTS) versions of Apollo Federation and Apollo Connectors. Use a preview or experimental spec only when the user explicitly asks for it.

Confirm the current LTS before writing @link URLs or federation_version. Prefer the GraphOS docs tools when they are available:

Federation: read /graphos/schema-design/federated-schemas/reference/versions and use the highest version marked LTS. That version is the schema @link (https://specs.apollo.dev/federation/vX.Y). Set federation_version in supergraph.yaml to the latest patch of that same LTS line.
Connectors: read /graphos/connectors/getting-started/version-requirements and /graphos/connectors/reference/changelog. Use the latest Connectors spec that is generally available (not marked experimental) and compatible with that Federation LTS (https://specs.apollo.dev/connect/vX.Y).

The template above uses the current LTS: Federation v2.15 and Connectors v0.3. If the docs list a newer LTS, use the docs.

Reference Files

Before implementing connectors, read the relevant reference files:

Grammar - Selection mapping EBNF syntax
Methods - Available transformation methods
Variables - Available mapping variables
Entities - Entity patterns and batching
Validation - Rover commands for validation
Troubleshooting - Common errors and solutions

Key Rules

Selection Mapping

Prefer sub-selections over ->map for cleaner mappings
Do NOT use $ when selecting fields directly from root
Field aliasing: newName: originalField (only when renaming)
Sub-selection: fieldName { ... } (to map nested content)

# DO - Direct sub-selection for arrays
$.results {
  firstName: name.first
  lastName: name.last
}

# DO NOT - Unnecessary root $
$ {
  id
  name
}

# DO - Direct field selection
id
name

Entities

Add @connect on a type to make it an entity (no @key needed)
Create entity stubs in parent selections: user: { id: userId }
When you see an ID field (e.g., productId), create an entity relationship
Each entity should have ONE authoritative subgraph with @connect

Literal Values

Use $() wrapper for literal values in mappings:

$(1)              # number
$(true)           # boolean
$("hello")        # string
$({"a": "b"})     # object

# In body
body: "$({ a: $args.a })"  # CORRECT
body: "{ a: $args.a }"     # WRONG - will not compose

Headers

http: {
  GET: "/api"
  headers: [
    { name: "Authorization", value: "Bearer {$env.API_KEY}" },
    { name: "X-Forwarded", from: "x-client" }
  ]
}

Batching

Convert N+1 patterns using $batch:

type Product @connect(
  source: "api"
  http: {
    POST: "/batch"
    body: "ids: $batch.id"
  }
  selection: "id name"
) {
  id: ID!
  name: String
}