apollo-connectors
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
- 最近更新
- 2026-05-22
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- apollo-connectors
- license
- MIT
- metadata
- { "author": "apollographql", "version": "1.0.0" }
- description
- 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".
- allowed-tools
- Bash(rover:*) Read Write Edit Glob Grep
- compatibility
- Requires rover CLI installed. Works with Claude Code and similar AI coding assistants.
02 资源文件 6
- 参考文档references/entities.md6.9 KB
- 参考文档references/grammar.md3.9 KB
- 参考文档references/methods.md5.6 KB
- 参考文档references/troubleshooting.md7.8 KB
- 参考文档references/validation.md7.6 KB
- 参考文档references/variables.md7.2 KB
03 SKILL.md 正文
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
->mapfor 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
@connecton a type to make it an entity (no@keyneeded) - 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
}
Ground Rules
- NEVER make up syntax or directive values not in this specification
- NEVER use
--elv2-license accept(for humans only) - ALWAYS ask for example API responses before writing code
- ALWAYS validate with
rover supergraph composeafter changes - ALWAYS create entity relationships when you see ID fields
- Prefer
$envover$configfor environment variables - Use
rover devfor running Apollo Router locally
04 同仓库更多 Skills
simpy
Process-based discrete-event simulation framework in Python. Use this skill when building simulations of systems with processes, queues, resources, and time-based events such as manufacturing systems, service operations, network traffic, logistics, or any system where entities interact with shared resources over time.
shopify-expert
Builds and debugs Shopify themes (.liquid files, theme.json, sections), develops custom Shopify apps (shopify.app.toml, OAuth, webhooks), and implements Storefront API integrations for headless storefronts. Use when building or customizing Shopify themes, creating Hydrogen or custom React storefronts, developing Shopify apps, implementing checkout UI extensions or Shopify Functions, optimizing performance, or integrating third-party services. Invoke for Liquid templating, Storefront API, app development, checkout customization, Shopify Plus features, App Bridge, Polaris, or Shopify CLI workflows.
shap
Model interpretability and explainability using SHAP (SHapley Additive exPlanations). Use this skill when explaining machine learning model predictions, computing feature importance, generating SHAP plots (waterfall, beeswarm, bar, scatter, force, heatmap), debugging models, analyzing model bias or fairness, comparing models, or implementing explainable AI. Works with tree-based models (XGBoost, LightGBM, Random Forest), deep learning (TensorFlow, PyTorch), linear models, and any black-box model.
shadcn-ui
Deep expertise on shadcn/ui component library including installation, customization, theming, and accessibility patterns. Use when building UI with shadcn/ui components, integrating Radix UI primitives, configuring Tailwind CSS v4 themes, or implementing dark mode. Covers Next.js App Router, Pages Router, and Vite setups.
seoul-subway-arrival
Look up Seoul real-time subway arrival information with the official Seoul Open Data API. Use when the user asks when a train arrives, which trains are approaching a station, or how crowded Seoul subway timing looks right now.
seo-optimization
Comprehensive 7-phase SEO optimization workflow covering technical SEO auditing, keyword research strategy, on-page optimization, content SEO and E-E-A-T, structured data implementation, link building, and AI search optimization. Use when auditing search engine visibility, diagnosing ranking issues, implementing schema markup, conducting keyword research, optimizing content for E-E-A-T signals, or adapting for AI-driven search (AI Overviews, SGE).