apollo-connectors

作者： apollographql

使用@source和@connect指令将REST API集成到GraphQL超级图中。提供结构化的5步流程：研究API结构、使用指令实现模式、通过rover supergraph compose验证、执行连接器以及测试覆盖。支持请求配置，包括标头、请求体负载、N+1模式的批处理以及通过$env注入环境变量。处理响应映射，包括字段选择、别名、嵌套数据的子选择以及实体...

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

下载 ZIP GitHub

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.12")
  @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: Always use federation/v2.12 and connect/v0.3 unless specified otherwise.

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
}