API style Introduced in L3

GraphQL

An API style where the client describes exactly what it wants in a single query. Solves REST's over-fetching, brings new operational complexity.

Mindmap

hover · click to navigate
this tech depends on / used by alternative Shipyard anchor
What it is

The plain-English version

GraphQL is an API query language and runtime, open-sourced by Facebook in 2015. The client sends a structured query ("give me this user, with their last 5 tasks, and for each task its comments and authors") and gets back exactly that shape — no more, no less. One endpoint, many shapes.

Why it exists

The problem it solves

REST often returns too much (over-fetching) or requires multiple round trips (under-fetching). GraphQL solves both — at the cost of cache control complexity, query performance gotchas (the N+1 problem), and a steeper server-side learning curve. Used at scale by GitHub, Shopify, Facebook.

What it competes with

Alternatives

AlternativeTypeWhen it wins
RESTAPI styleThe dominant pattern for APIs over HTTP. Resources, methods, status codes — the vocabulary every backend speaks.
Where it shows up in Shipyard

Deep links

Vocabulary

The words you'll hear

Schema
The type system. Defines what queries are valid.
Query / Mutation / Subscription
Read / write / real-time.
Resolver
A function that fetches the data for a given field.
N+1
The classic GraphQL trap: 1 query for users, then N more for each user's tasks. DataLoader exists to batch these.
Federation
Composing multiple GraphQL services into one schema. Apollo Federation is the dominant pattern.
Persisted queries
Sending only a query ID instead of the query text. Performance + safety.
Prompting

Bad vs. good prompt for GraphQL

✕ Bad prompt
set up graphql
✓ Good prompt
Set up Apollo Server (v4) with TypeScript on Express in our existing Node project. Define a schema for Task (id, title, status, assigneeId) and User (id, name, email). Add resolvers that fetch from our Postgres via Prisma. Use DataLoader to batch the User lookups inside Task resolvers (avoid N+1).

Why it works: Names the server (Apollo v4), language, integration (Prisma), and explicitly addresses the N+1 trap with DataLoader. The agent picks the right tool combination instead of guessing among Apollo, Yoga, Mercurius.

Pitfalls

What bites real teams

⚠ N+1 resolver explosion

GraphQL makes N+1 patterns very easy to write and very hard to spot until production. DataLoader from day one.

⚠ Caching is harder

REST caches with HTTP. GraphQL needs Apollo Client cache or persisted queries with CDN cooperation.

⚠ Over-permissive queries

Without limits, a malicious client can ask for an enormous nested query and DoS your server. Use depth/complexity limits.

References

Official docs only