Index of every page on this site: llms.txt
All skills
apollographql avatar

/apollo-connectors

@9dda139 official
by Apollo GraphQLapollographql/skills134 stars
14
Run it yourself

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".

Use this Skill: https://skilld.dev/gh/apollographql/skills/apollo-connectors

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈160 tokens for metadata: the name and description. ≈1.6k when used: this file. ≈10k more on demand in 6 files.

Description uses 8.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈639 characters, or 8.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Apollo Connectors Schema Assistant

Deprecated. This skill is superseded by the 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:

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
}

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 compose after changes
  • ALWAYS create entity relationships when you see ID fields
  • Prefer $env over $config for environment variables
  • Use rover dev for running Apollo Router locally

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning1mo5 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    The skill provides instructions and references for creating Apollo Connectors subgraphs to integrate REST APIs into GraphQL. It uses the official 'rover' CLI for schema validation and testing. The primary security consideration is a standard vulnerability surface for indirect prompt injection when the agent processes external API documentation or user-provided responses to generate code.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

  • Runlayer9mo

    7/7 files flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 9dda139. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 weeks ago.

Activeupdated last month
What it can do
Runs commands
metadata
{
  "author": "apollographql",
  "version": "1.1.2"
}
All 1 allowed tools
Bash(rover:*) Read Write Edit Glob Grep
Other metadata
compatibility
Requires rover CLI installed. Works with Claude Code and similar AI coding assistants.
  • graphql
  • apollo
  • rest-api
  • connectors
  • federation
  • schema
  • integration

README badge

README badge for apollographql/skills/apollo-connectors

Integrates REST APIs into GraphQL supergraphs using Apollo Connectors with @source and @connect directives. Targets the rover CLI workflow and follows a five-step process: research the API, implement the schema, validate with rover compose, execute with rover connector run, and test coverage.

Generated from the current SKILL.md.

What versions of Apollo federation and connectors does this skill support?
The skill uses federation v2.12 and connect v0.3 by default unless you specify otherwise.
Do I need rover CLI installed to use this skill?
Yes. The skill requires rover CLI installed and uses commands like `rover supergraph compose`, `rover connector run`, and `rover connector test`.
Can this skill integrate any REST API into GraphQL?
Yes. The skill handles REST API integration using @source and @connect directives, supporting GET/POST requests, headers, batching, and response field mapping.
Does this skill handle entity relationships and N+1 query patterns?
Yes. The skill creates entity relationships when ID fields are present and converts N+1 patterns using batching with the $batch variable.
What happens if composition or connector execution fails?
The skill follows a 5-step validation process that runs `rover supergraph compose` after schema changes and `rover connector run` before testing, catching errors before they reach production.

Generated from the current SKILL.md. These answers refresh after source changes.