agentleFS
pabloirracionalpabloirracional/claude-skills/skills/building-graphql-apis/SKILL.md

building-graphql-apis

Skill0 starsChanged 4 months agoMITView on GitHub

Designs GraphQL schemas and resolvers using Apollo Server, with a measured demonstration of the N+1 query problem and the dataloader fix - not just the claim that batching matters. Use whenever the user wants to build a GraphQL API, design a GraphQL schema, or write queries/mutations/resolvers.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Measured result: 1 DB call for the same 5 books: - all the author lookups for a single request collapse into one batched call, regardless …

    line 34
  2. Very specific:

    Every context-scoped loader (like authorLoader above) needs to be created fresh per request, never shared across requests - a loader's …

    line 56

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Building GraphQL APIs

Designs a GraphQL schema and resolvers that stay maintainable as the API grows, grounded in a real measured fix for the most common GraphQL performance bug.

Workflow

  1. Model the schema around the client's needs, not the database shape - don't just mirror SQL tables as types.
  2. Nullability is a deliberate choice: a field is nullable if it can legitimately fail to resolve - don't make everything nullable defensively.
  3. Resolvers stay thin: business logic lives in a service layer the resolver calls into, not inline in the resolver function.
  4. Avoid the N+1 problem with batching - see the measured proof below. This isn't a theoretical concern; it's the single most common GraphQL performance bug in production.
  5. Mutations return the changed object, not just a success boolean - confirmed pattern below.

Measured proof: the N+1 problem and its fix

Tested against a real running Apollo Server instance (@apollo/server), with a Query.books → Book.author relationship - the textbook N+1 shape (one query returning a list, each item needing one more lookup).

Query: { books { id title author { name } } } against 5 books.

Naive resolver (looks up the author fresh for every book):

Book: { author: (book) => naiveGetAuthorById(book.authorId) }

Measured result: 5 separate DB calls for 5 books - the "N+1" is literal here: 1 call for the books list, then N more for each book's author.

Batched resolver (dataloader-style: queue lookups, dispatch once per tick):

Book: { author: (book, args, context) => context.authorLoader.load(book.authorId) }

Measured result: 1 DB call for the same 5 books - all the author lookups for a single request collapse into one batched call, regardless of how many books are in the list.

This is why production GraphQL APIs need a batching layer (the dataloader package, or Apollo's built-in equivalents) on any field that resolves a relationship - without it, list queries scale linearly with DB calls, and that's invisible in development with small test data but severe in production.

Confirmed pattern: mutations return the updated object

type Mutation { renameBook(id: ID!, title: String!): Book! }
renameBook: (_parent, { id, title }) => {
  const book = books.find(b => b.id === Number(id));
  book.title = title;
  return book;
}

Tested result: { "renameBook": { "id": "1", "title": "Renamed Book" } } - the client gets the updated data back in the same round trip, instead of a bare { success: true } that would force a second query to see the change.

Notes

  • The demo above implements the batching queue inline with no dependency, to keep the proof self-contained - in a real project, use the dataloader npm package rather than hand-rolling this, it handles edge cases (per-request cache scoping, error handling per key) this demo simplifies away.
  • For multi-team APIs, mention Apollo Federation as an option to split the schema across services instead of one monolithic schema.
  • Every context-scoped loader (like authorLoader above) needs to be created fresh per request, never shared across requests - a loader's cache living longer than one request will serve stale data to later requests.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.