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.
In this repository19 other files it gives its agents.
- adding-authenticationSkill
- auditing-seoSkill
- automating-git-workflowsSkill
- building-email-sequencesSkill
- building-wordpress-pluginsSkill
- designing-carouselsSkill
- fine-tuning-ml-modelsSkill
- handling-web-formsSkill
- n8n-automationSkill
- organizing-spreadsheetsSkill
- reviewing-cloudflare-workers-codeSkill
- reviewing-code-for-securitySkill
- scaffolding-landing-pagesSkill
- setting-up-error-monitoringSkill
- setting-up-firebase-authSkill
- using-nextjs-best-practicesSkill
- working-with-postgres-databasesSkill
- writing-marketing-copySkill
- writing-terraform-codeSkill
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
- Distinctive: line 34
Measured result: 1 DB call for the same 5 books: - all the author lookups for a single request collapse into one batched call, regardless …
- Very specific: line 56
Every context-scoped loader (like authorLoader above) needs to be created fresh per request, never shared across requests - a loader's …
≈ “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.
Files
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
- Model the schema around the client's needs, not the database shape - don't just mirror SQL tables as types.
- Nullability is a deliberate choice: a field is nullable if it can legitimately fail to resolve - don't make everything nullable defensively.
- Resolvers stay thin: business logic lives in a service layer the resolver calls into, not inline in the resolver function.
- 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.
- 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
dataloadernpm 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 (likeauthorLoaderabove) 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.
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
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.

