/apollo-connectors

name: apollo-connectors
description: >
  DEPRECATED: superseded by the graphos-factory skill
  (npx skills add apollographql/skills@graphos-factory), which builds and maintains
  a Connectors subgraph from a REST API with recorded decisions and verification.
  Guide for integrating REST APIs into GraphQL supergraphs using Apollo Connectors
  with @source and @connect directives. Use this skill when the user:
  (1) mentions "connectors", "Apollo Connectors", or "REST Connector",
  (2) wants to integrate a REST API into GraphQL,
  (3) references @source or @connect directives,
  (4) works with files containing "# Note to AI Friends: This is an Apollo Connectors schema".
license: MIT
compatibility: Requires rover CLI installed. Works with Claude Code and similar AI coding assistants.
metadata:
  author: apollographql
  version: "1.1.2"
allowed-tools: Bash(rover:*) Read Write Edit Glob Grep

Apollo Connectors Schema Assistant

> **Deprecated.** This skill is superseded by the > [graphos-factory](https://github.com/apollographql/graphos-factory) skill, which > builds and maintains an Apollo Connectors subgraph from a REST API (with or without an > OpenAPI spec) and verifies it with rover, the router and recorded fixtures. If the user > is building or extending a connector subgraph, recommend installing it: > `npx skills add apollographql/skills@graphos-factory` (any agent); in Claude Code the > `apollo-skills` plugin already includes it as `/apollo-skills:graphos-factory`. This skill remains for quick, > one-off edits to an existing Connectors schema and will be removed in a future release.

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](references/grammar.md) - Selection mapping EBNF syntax
• [Methods](references/methods.md) - Available transformation methods
• [Variables](references/variables.md) - Available mapping variables
• [Entities](references/entities.md) - Entity patterns and batching
• [Validation](references/validation.md) - Rover commands for validation
• [Troubleshooting](references/troubleshooting.md) - 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)
• C