graphql-apis

GraphQL APIs AI Skill Guide (Claude)

Overview & Engine Architecture

GraphQL exposes a typed schema (types, queries, mutations, subscriptions) where clients select fields. The runtime parses → validates → executes resolvers. Naive per-field DB access causes N+1 query fan-out. Agents design schemas for product use cases, enforce authz in resolvers/fields, batch with per-request DataLoaders, paginate lists, and harden public graphs with depth/complexity limits and optional persisted/allowlisted operations.

┌─────────────────────────────────────────────────────────────┐
│                 GraphQL request path                          │
│                                                             │
│  Client operation (+ variables, operation name)             │
│  ├── parse / validate (depth · complexity · auth directives)│
│  └── execute field resolvers                                │
│                                                             │
│  Context (per request)                                      │
│  ├── user / auth principal                                  │
│  ├── DataLoaders (request-scoped only)                      │
│  └── services / @prisma / DB                                │
│                                                             │
│  Hardening                                                  │
│  └── pagination · error masking · persisted queries (opt)   │
└─────────────────────────────────────────────────────────────┘

When to use / when not to

Use when

• Designing or evolving GraphQL schemas; implementing resolvers without N+1.
• Adding authn/authz around sensitive types/fields; setting pagination and cost limits.
• Pairing GraphQL with @express, @nodejs, @nextjs (Route Handlers), or other HTTP hosts.

Do not use when

• A simple CRUD REST surface is enough and the team has no GraphQL clients → @express REST.
• The work is only ORM migrations/schema → @prisma / @postgresql.
• Someone asks to expose introspection + unlimited depth on a public internet API with no auth → refuse; add limits and authz first.