graphql_basics v1.0.0

name: "graphql_basics" description: "Querying GraphQL APIs: selection sets, variables, fragments, cursor pagination, introspection, and error handling for agents fetching data from GraphQL endpoints. Triggers on: query a GraphQL API, write a GraphQL query, fetch data via GraphQL, introspect a schema, paginate GraphQL results." metadata: { "includeInPrompt": true }

Purpose

Fetch data from GraphQL APIs correctly and efficiently: write queries that ask for exactly the fields needed, pass arguments via variables (never string interpolation), page through connection-style results, discover a schema via introspection, and handle GraphQL's distinctive error model (errors come back inside a 200 response). Scoped to querying an existing API — designing a GraphQL schema or operating a server is a different problem.

Workflow

1. Shape the selection set. A GraphQL query names the exact fields you want; the server returns only those. Start minimal and add fields as needed — over-fetching is the one failure mode REST trained you into; GraphQL gives you the control, so use it. Nested objects select nested fields. Aliases (me: user(login: "x")) let the same field appear twice with different arguments.

1. Pass arguments via variables, never string interpolation. Define $vars at the top of the query and send them as a separate variables JSON object. Interpolating user input into the query string is an injection risk and breaks caching.

1. Post the query as JSON. A GraphQL operation is an HTTP POST to the endpoint with Content-Type: application/json and a body of {"query": "...", "variables": {...}} (an operationName key disambiguates when the document holds several operations).

Example with a public demo endpoint (the command shape is standard GraphQL-over-HTTP; confirm the endpoint responds before depending on it):

bash
curl -s -X POST https://countries.trevorblades.com/ \
  -H "Content-Type: application/json" \
  -d '{"query":"query GetCountry($code: ID!) { country(code: $code) { name capital currency } }","variables":{"code":"US"}}'

Expected response shape: {"data": {"country": {"name": ..., "capital": ..., "currency": ...}}} — fields exactly as requested, nothing more.

1. Paginate connection-style results. The Relay connection pattern is the common convention: a field returns edges { node { ... } cursor } and pageInfo { hasNextPage endCursor }. Loop: request first: N, after: $cursor, collect edges, set $cursor = pageInfo.endCursor, repeat while pageInfo.hasNextPage is true. Prefer this over offset-style args when the API offers both — cursors stay stable when rows are inserted mid-pagination.

1. Reuse fragments. A fragment defines a field set once and spreads it wherever needed — one query pulling users in two places defines fragment UserFields on User { id name } and uses ...UserFields in both. Keeps large queries consistent and smaller.

1. Introspect the schema before guessing. If the API has docs disabled, run an introspection query to list types and fields — never invent field names. Introspection can be disabled on hardened APIs; then fall back to the provider's docs or schema file.

graphql
query {
  __schema {
    queryType { fields { name } }
    mutationType { fields { name } }
  }
}

For one type's fields: query { __type(name: "Country") { fields { name type { name } } } }.

1. Handle GraphQL errors correctly. A GraphQL server can return HTTP 200 with an errors array alongside partial data. Always check for an errors key in the response JSON — don't trust HTTP status alone. Non-2xx statuses are transport-level failures (auth, rate limit, wrong endpoint); the errors array is operation-level (bad field, validation, null in a non-null position). Retry the former, fix the query for the latter.

Output Contract

After applying this skill, an agent should produce:

• A GraphQL query string with a named operation, a minimal selection set, fragments where fields repeat, and all arguments passed through a variables object.
• A curl (or equivalent) invocation showing the POST body format and the endpoint, with the response fields it expects back.
• For paginated data: a loop sketch using edges/pageInfo/endCursor with the termination condition stated (hasNextPage == false).
• Any introspection result it relied on (types/fields discovered), so a reader can verify the field names are real.

Operating Rules

• Variables over interpolation. Every argument value goes in variables; no value ever gets concatenated into the query string. This is the injection rule for GraphQL.
• Ask for only what you need. Requesting the whole object "just in case" defeats the point of the query language and can trigger cost-limit rejections on metered APIs.
• Verify field names before running. Run an introspection query (or check docs) for any type you haven't queried before — a guessed field name is a silent failure that returns an errors entry instead of data.
• Check the errors key on every response. HTTP 200 does not mean success in GraphQL. Treat a non-empty errors array as the operation having failed, even when data is partially present.
• Cursor pagination over offsets. When an API offers connection-style pagination, use it; offsets shift under concurrent writes, cursors don't.
• Introspection is a tool, not a weapon. Some APIs disable it for a reason; don't route around a disabled introspection endpoint to probe internals — use the published docs.
• Soften absolutes. "Prefer variables" is stated as the rule with the reason (injection + cacheability); "check introspection when the API is unfamiliar" beats "always introspect".