## Introduction: Why GraphQL Exists In 2012, Facebook had a problem. Their mobile app was slow, data-hungry, and difficult to evolve. The REST APIs that powered the web experience were sending too much data for mobile screens. Getting the right data for a single view required hitting multiple endpoints. And every time the mobile team needed a new field, the backend team had to update an endpoint or create a new one. So Facebook built GraphQL — a query language that lets the client ask for exactly the data it needs, in a single request, with a strongly typed schema that both sides agree on. GraphQL was open-sourced in 2015 and has since been adopted by GitHub, Shopify, Spotify, Twitter, Airbnb, The New York Times, and thousands of other companies. It's not a replacement for REST in all cases, but for the problems it solves, it solves them exceptionally well. What GraphQL actually is: - **A query language for APIs** — not a database, not a library, not a framework. It's a specification for how clients can request data from servers. - **A runtime** — you implement resolvers (functions) that fetch the data for each field. GraphQL executes these resolvers based on what the client asks for. - **A type system** — every piece of data is typed. The schema serves as a contract between client and server. > GraphQL is to APIs what SQL is to databases: a declarative language for asking for data. Instead of "give me everything from this endpoint," you say "give me the user's name and their last 5 posts." The server returns exactly that — nothing more, nothing less. By the end of this guide you will: - Understand what GraphQL is, why it exists, and how it compares to REST - Write schemas using the Schema Definition Language (SDL) - Build queries, mutations, and subscriptions - Implement resolvers with TypeScript - Solve the N+1 problem with DataLoader - Handle authentication, authorization, and error handling - Implement pagination (offset and cursor-based) - Understand caching strategies on both client and server - Secure and optimize a GraphQL API for production - Achieve end-to-end type safety with TypeScript codegen - Know when to use GraphQL and when REST is the better choice --- ## GraphQL vs REST Before diving into GraphQL, let's understand the problems it solves by comparing it to REST. ### The REST Approach Imagine building a user profile page that shows the user's name, avatar, their 5 most recent posts, and the number of followers. In REST: ``` GET /api/users/123 → { id, name, avatar, email, bio, createdAt, settings, ... } GET /api/users/123/posts → [{ id, title, body, tags, createdAt, comments, ... }, ...] GET /api/users/123/followers → { count: 1234, followers: [...] } ``` Three requests. Each returns more data than you need. The user endpoint returns `settings` and `bio` that the profile card doesn't display. The posts endpoint returns full `body` and `comments` when you only need titles. The followers endpoint returns the full list when you only need the count. This is **over-fetching** (getting more data than needed) and **under-fetching** (needing multiple requests to assemble one view). ### The GraphQL Approach The same data in a single GraphQL query: ```graphql query UserProfile { user(id: "123") { name avatar followers { count } posts(last: 5) { title createdAt } } } ``` One request. The response contains exactly what was asked for — nothing more: ```json { "data": { "user": { "name": "Ray Silvers", "avatar": "https://example.com/ray.jpg", "followers": { "count": 1234 }, "posts": [ { "title": "Understanding GraphQL", "createdAt": "2026-02-20" }, { "title": "TypeScript Generics", "createdAt": "2026-02-22" } ] } } } ``` ### Comparison Table | Aspect | REST | GraphQL | |--------|------|---------| | Endpoints | Multiple (one per resource) | Single endpoint (`/graphql`) | | Data fetching | Server decides what to return | Client specifies exactly what it needs | | Over-fetching | Common | Eliminated by design | | Under-fetching | Requires multiple requests | Single query for nested data | | Versioning | URL versioning (`/v1/`, `/v2/`) | Schema evolution with deprecation | | Type safety | Requires OpenAPI/Swagger docs | Built into the schema | | Caching | HTTP caching works naturally (GET) | Requires client-side normalized caching | | File uploads | Straightforward with multipart | Needs special handling (multipart spec) | | Learning curve | Familiar to most developers | Steeper initial learning curve | | Tooling | Mature ecosystem | Rich ecosystem (Playground, codegen) | ### When to Use Which **Choose REST when:** - Your API is simple CRUD with predictable access patterns - HTTP caching is critical (CDN-friendly GET requests) - You're building a public API consumed by many different clients - File uploads are a core feature - Your team is more familiar with REST **Choose GraphQL when:** - Different clients need different data shapes (mobile vs web vs internal tools) - You have deeply nested or related data - The frontend team needs to move fast without waiting for backend changes - You want a strongly typed API contract - You're building a BFF (Backend for Frontend) layer **Use both when:** - REST for simple resources and file operations, GraphQL for complex data requirements - This is more common than you'd think in production systems --- ## Core Concepts: The Schema The schema is the foundation of every GraphQL API. It defines the types, their fields, and the relationships between them. Think of it as the contract between client and server. ### Schema Definition Language (SDL) GraphQL has its own language for defining schemas: ```graphql type User { id: ID! name: String! email: String! avatar: String bio: String posts: [Post!]! followers: [User!]! createdAt: DateTime! } type Post { id: ID! title: String! body: String! author: User! tags: [String!]! comments: [Comment!]! published: Boolean! createdAt: DateTime! updatedAt: DateTime! } type Comment { id: ID! body: String! author: User! post: Post! createdAt: DateTime! } ``` ### Scalar Types GraphQL comes with five built-in scalar types: | Type | Description | Example | |------|-------------|---------| | `Int` | 32-bit integer | `42` | | `Float` | Double-precision float | `3.14` | | `String` | UTF-8 string | `"hello"` | | `Boolean` | True or false | `true` | | `ID` | Unique identifier (serialized as String) | `"abc-123"` | You can define custom scalars for things like `DateTime`, `JSON`, `URL`, and `Email`. ### The Root Types Every schema has up to three root types that serve as entry points: ```graphql type Query { user(id: ID!): User users(limit: Int, offset: Int): [User!]! post(id: ID!): Post posts(tag: String): [Post!]! } type Mutation { createUser(input: CreateUserInput!): User! updateUser(id: ID!, input: UpdateUserInput!): User! deleteUser(id: ID!): Boolean! createPost(input: CreatePostInput!): Post! } type Subscription { postCreated: Post! commentAdded(postId: ID!): Comment! } ``` - **Query** — read operations (like GET in REST) - **Mutation** — write operations (like POST/PUT/DELETE) - **Subscription** — real-time operations (WebSocket-based) ### Input Types Input types define the shape of data clients send: ```graphql input CreateUserInput { name: String! email: String! avatar: String bio: String } input UpdateUserInput { name: String email: String avatar: String bio: String } ``` Input types look like regular types but use the `input` keyword. They can only contain scalar types, enums, and other input types — no object types or circular references. ### Enums ```graphql enum Role { ADMIN MODERATOR USER GUEST } enum PostStatus { DRAFT PUBLISHED ARCHIVED } type User { id: ID! name: String! role: Role! } ``` Enums are type-safe constants. The server validates that only valid values are used. --- ## Queries Queries are how clients read data. The power of GraphQL is that the client specifies the exact shape of the response. ### Basic Query ```graphql query { user(id: "123") { name email } } ``` Response: ```json { "data": { "user": { "name": "Ray Silvers", "email": "ray@example.com" } } } ``` ### Nested Queries You can traverse relationships in a single query: ```graphql query { user(id: "123") { name posts { title comments { body author { name } } } } } ``` This returns the user, their posts, each post's comments, and each comment's author — all in one round trip. ### Arguments Fields can accept arguments: ```graphql query { posts(limit: 10, tag: "typescript", sortBy: CREATED_AT) { title createdAt } } ``` ### Aliases When you need the same field with different arguments: ```graphql query { recentPosts: posts(limit: 5, sortBy: CREATED_AT) { title } popularPosts: posts(limit: 5, sortBy: LIKES) { title } } ``` Without aliases, both fields would be `posts` and conflict. Aliases rename them in the response. ### Fragments Reusable field selections: ```graphql fragment UserBasic on User { id name avatar } query { user(id: "123") { ...UserBasic email bio } post(id: "456") { title author { ...UserBasic } } } ``` Fragments reduce duplication when the same fields are needed in multiple places. ### Variables Hard-coding values in queries is bad practice. Variables make queries reusable: ```graphql query GetUser($userId: ID!, $postLimit: Int = 10) { user(id: $userId) { name posts(limit: $postLimit) { title } } } ``` Variables are passed separately from the query: ```json { "userId": "123", "postLimit": 5 } ``` ### Typed Query in TypeScript With codegen, queries become fully typed: ```ts import { gql } from '@apollo/client'; const GET_USER = gql` query GetUser($userId: ID!) { user(id: $userId) { id name email posts { id title } } } `; interface GetUserData { user: { id: string; name: string; email: string; posts: { id: string; title: string }[]; }; } interface GetUserVars { userId: string; } const { data, loading, error } = useQuery(GET_USER, { variables: { userId: '123' }, }); if (data) { console.log(data.user.name); // fully typed console.log(data.user.posts[0].title); // fully typed } ``` --- ## Mutations Mutations modify data — create, update, delete. They follow the same syntax as queries but use the `mutation` keyword. ### Creating Data ```graphql mutation CreatePost($input: CreatePostInput!) { createPost(input: $input) { id title createdAt author { name } } } ``` Variables: ```json { "input": { "title": "GraphQL Deep Dive", "body": "A comprehensive guide to GraphQL...", "tags": ["graphql", "api", "typescript"] } } ``` The mutation returns the created post — the client specifies which fields of the new post it wants back. This eliminates the need for a follow-up GET request. ### Updating Data ```graphql mutation UpdatePost($id: ID!, $input: UpdatePostInput!) { updatePost(id: $id, input: $input) { id title updatedAt } } ``` ### Deleting Data ```graphql mutation DeletePost($id: ID!) { deletePost(id: $id) { success message } } ``` ### Multiple Mutations in One Request ```graphql mutation BatchOperations { publishPost: updatePost(id: "1", input: { published: true }) { id published } archivePost: updatePost(id: "2", input: { status: ARCHIVED }) { id status } } ``` Mutations in a single request execute **sequentially** (unlike queries which can execute in parallel). This guarantees order when it matters. ### TypeScript Mutation with Apollo Client ```ts const CREATE_POST = gql` mutation CreatePost($input: CreatePostInput!) { createPost(input: $input) { id title } } `; interface CreatePostData { createPost: { id: string; title: string }; } interface CreatePostVars { input: { title: string; body: string; tags: string[] }; } const [createPost, { data, loading, error }] = useMutation( CREATE_POST, { update(cache, { data }) { if (data) { cache.modify({ fields: { posts(existingPosts = []) { const newPostRef = cache.writeFragment({ data: data.createPost, fragment: gql`fragment NewPost on Post { id title }`, }); return [...existingPosts, newPostRef]; }, }, }); } }, } ); await createPost({ variables: { input: { title: 'New Post', body: 'Content here', tags: ['graphql'] }, }, }); ``` The `update` function manually updates the Apollo cache so the UI reflects the new post without a refetch. --- ## Subscriptions Subscriptions provide real-time updates over WebSockets. When something changes on the server, subscribed clients receive the update immediately. ### Schema ```graphql type Subscription { postCreated: Post! commentAdded(postId: ID!): Comment! messageReceived(chatId: ID!): Message! } ``` ### Client Usage ```ts const COMMENT_ADDED = gql` subscription OnCommentAdded($postId: ID!) { commentAdded(postId: $postId) { id body author { name } createdAt } } `; function PostComments({ postId }: { postId: string }) { const { data, loading } = useSubscription(COMMENT_ADDED, { variables: { postId }, }); if (data) { console.log('New comment:', data.commentAdded.body); } return /* render comments */; } ``` ### When to Use Subscriptions vs Polling | Approach | Use When | |----------|----------| | **Subscriptions** | Real-time chat, live notifications, collaborative editing | | **Polling** | Dashboard data that updates every 30s, data that doesn't need instant updates | | **Refetch on mutation** | Data that only changes when the current user acts | Subscriptions add complexity (WebSocket infrastructure, connection management, reconnection logic). Don't use them when polling or refetching is sufficient. --- ## Resolvers: Where the Magic Happens Resolvers are functions that produce the data for each field in the schema. When a query comes in, GraphQL walks the query tree and calls the appropriate resolver for each field. ### The Resolver Signature Every resolver receives four arguments: ```ts type Resolver = (parent: any, args: any, context: any, info: any) => any; ``` | Argument | Description | |----------|-------------| | `parent` | The result from the parent resolver (for nested fields) | | `args` | Arguments passed to the field in the query | | `context` | Shared context (auth, database connections, DataLoaders) | | `info` | Information about the query execution (rarely used directly) | ### TypeScript Resolvers ```ts interface Context { db: Database; currentUser: User | null; loaders: DataLoaders; } const resolvers = { Query: { user: async (_parent: unknown, args: { id: string }, context: Context): Promise => { return context.db.users.findById(args.id); }, posts: async ( _parent: unknown, args: { limit?: number; tag?: string }, context: Context ): Promise => { const { limit = 20, tag } = args; if (tag) { return context.db.posts.findByTag(tag, limit); } return context.db.posts.findAll(limit); }, }, Mutation: { createPost: async ( _parent: unknown, args: { input: CreatePostInput }, context: Context ): Promise => { if (!context.currentUser) { throw new GraphQLError('Not authenticated', { extensions: { code: 'UNAUTHENTICATED' }, }); } return context.db.posts.create({ ...args.input, authorId: context.currentUser.id, }); }, }, User: { posts: async (parent: User, _args: unknown, context: Context): Promise => { return context.loaders.postsByAuthor.load(parent.id); }, followers: async (parent: User, _args: unknown, context: Context): Promise => { return context.loaders.followersByUser.load(parent.id); }, }, Post: { author: async (parent: Post, _args: unknown, context: Context): Promise => { return context.loaders.userById.load(parent.authorId); }, comments: async (parent: Post, _args: unknown, context: Context): Promise => { return context.loaders.commentsByPost.load(parent.id); }, }, }; ``` ### The Resolver Chain When a query executes: ```graphql query { user(id: "123") { # Calls Query.user resolver name # Default resolver (returns parent.name) posts { # Calls User.posts resolver title # Default resolver (returns parent.title) author { # Calls Post.author resolver name # Default resolver (returns parent.name) } } } } ``` GraphQL starts at the `Query.user` resolver. Its return value becomes the `parent` for the `User` field resolvers. Each level cascades down. Fields without custom resolvers use the **default resolver**, which simply returns `parent[fieldName]`. > The resolver chain is like a waterfall. Data flows down from parent to child. Each resolver receives what its parent returned and can enrich, transform, or fetch additional data. --- ## Type System Deep Dive ### Nullability In GraphQL, fields are **nullable by default**. The `!` operator makes a field non-null: ```graphql type User { name: String! # Never null — server guarantees a value bio: String # Can be null posts: [Post!]! # The list is never null, AND each item is never null tags: [String!] # The list can be null, but items inside can't be null comments: [String]! # The list is never null, but items inside can be null } ``` This matters because: - If a non-null field would resolve to `null`, GraphQL propagates the null **up** to the nearest nullable parent. This can unexpectedly null out an entire object. - Starting nullable and adding `!` later is a non-breaking change. Starting non-null and removing `!` is a breaking change. > The GraphQL community recommends **nullable by default**. Only add `!` when you're certain the field will always have a value. This makes your schema more resilient to partial failures. ### Interfaces and Unions **Interfaces** define a shared set of fields: ```graphql interface Node { id: ID! } interface Timestamped { createdAt: DateTime! updatedAt: DateTime! } type User implements Node & Timestamped { id: ID! name: String! createdAt: DateTime! updatedAt: DateTime! } type Post implements Node & Timestamped { id: ID! title: String! createdAt: DateTime! updatedAt: DateTime! } ``` **Unions** represent "one of these types" without shared fields: ```graphql union SearchResult = User | Post | Comment type Query { search(query: String!): [SearchResult!]! } ``` Querying a union requires **inline fragments**: ```graphql query { search(query: "graphql") { ... on User { name avatar } ... on Post { title author { name } } ... on Comment { body post { title } } } } ``` ### Custom Scalars ```graphql scalar DateTime scalar JSON scalar URL scalar EmailAddress ``` Implementation in TypeScript: ```ts import { GraphQLScalarType, Kind } from 'graphql'; const DateTimeScalar = new GraphQLScalarType({ name: 'DateTime', description: 'ISO 8601 date-time string', serialize(value: Date): string { return value.toISOString(); }, parseValue(value: string): Date { return new Date(value); }, parseLiteral(ast): Date | null { if (ast.kind === Kind.STRING) { return new Date(ast.value); } return null; }, }); ``` ### Directives Directives annotate schema elements or query operations: ```graphql # Built-in query directives query GetUser($includeEmail: Boolean!, $skipBio: Boolean!) { user(id: "123") { name email @include(if: $includeEmail) bio @skip(if: $skipBio) } } # Schema directive for deprecation type User { name: String! fullName: String! @deprecated(reason: "Use 'name' instead") } ``` --- ## Building a GraphQL Server ### With GraphQL Yoga and TypeScript GraphQL Yoga is a modern, spec-compliant GraphQL server: ```ts import { createSchema, createYoga } from 'graphql-yoga'; import { createServer } from 'http'; const typeDefs = /* GraphQL */ ` type Query { hello(name: String): String! users: [User!]! } type User { id: ID! name: String! email: String! } `; const users = [ { id: '1', name: 'Ray', email: 'ray@example.com' }, { id: '2', name: 'Alex', email: 'alex@example.com' }, ]; const resolvers = { Query: { hello: (_: unknown, { name }: { name?: string }) => `Hello, ${name ?? 'World'}!`, users: () => users, }, }; const yoga = createYoga({ schema: createSchema({ typeDefs, resolvers }), }); const server = createServer(yoga); server.listen(4000, () => { console.log('GraphQL server running at http://localhost:4000/graphql'); }); ``` ### Schema-First vs Code-First | Approach | Description | Tools | Pros | Cons | |----------|-------------|-------|------|------| | **Schema-first** | Write `.graphql` files, generate TypeScript types | GraphQL Code Generator, graphql-yoga | Schema is the source of truth, readable SDL | Schema and resolvers can drift apart | | **Code-first** | Write TypeScript, schema is generated | Pothos, Nexus, TypeGraphQL | Single source of truth in code, no drift | Schema can be harder to read, heavier abstractions | Schema-first is the more traditional approach and what most tutorials teach. Code-first is gaining popularity because it eliminates the gap between schema and implementation. ### Code-First with Pothos ```ts import SchemaBuilder from '@pothos/core'; const builder = new SchemaBuilder({}); const UserType = builder.objectRef('User'); builder.objectType(UserType, { fields: (t) => ({ id: t.exposeID('id'), name: t.exposeString('name'), email: t.exposeString('email'), posts: t.field({ type: [PostType], resolve: (user, _args, ctx) => ctx.db.posts.findByAuthor(user.id), }), }), }); builder.queryType({ fields: (t) => ({ user: t.field({ type: UserType, nullable: true, args: { id: t.arg.id({ required: true }) }, resolve: (_root, args, ctx) => ctx.db.users.findById(args.id), }), }), }); export const schema = builder.toSchema(); ``` The schema is generated from the TypeScript code — types are inferred, resolvers are checked at compile time, and there's no `.graphql` file to keep in sync. --- ## The N+1 Problem and DataLoader The N+1 problem is the most common performance issue in GraphQL. Understanding it is essential. ### The Problem Consider this query: ```graphql query { posts(limit: 10) { title author { name } } } ``` With naive resolvers: 1. `Query.posts` fetches 10 posts (1 query) 2. For each post, `Post.author` fetches the author (10 queries) Total: **11 database queries** for what should logically be 2. If each post also has comments with authors, you could easily hit 100+ queries. ### DataLoader: The Solution DataLoader batches and deduplicates requests within a single tick of the event loop: ```ts import DataLoader from 'dataloader'; function createLoaders(db: Database) { return { userById: new DataLoader(async (ids) => { const users = await db.users.findByIds([...ids]); const userMap = new Map(users.map((u) => [u.id, u])); return ids.map((id) => userMap.get(id) ?? new Error(`User ${id} not found`)); }), postsByAuthor: new DataLoader(async (authorIds) => { const posts = await db.posts.findByAuthorIds([...authorIds]); const grouped = new Map(); posts.forEach((post) => { const existing = grouped.get(post.authorId) ?? []; existing.push(post); grouped.set(post.authorId, existing); }); return authorIds.map((id) => grouped.get(id) ?? []); }), }; } ``` Now the resolver uses the loader: ```ts Post: { author: (parent: Post, _args: unknown, context: Context) => { return context.loaders.userById.load(parent.authorId); }, } ``` What happens: 1. `Query.posts` fetches 10 posts (1 query) 2. Ten `Post.author` resolvers each call `loader.load(authorId)` 3. DataLoader batches all 10 IDs into a single call: `findByIds(['1', '2', '3', ...])` 4. Total: **2 queries** instead of 11 DataLoader also deduplicates — if 5 posts have the same author, that author is only fetched once. > DataLoader is per-request. Create new loaders for each request to avoid caching data across different users. Attach them to the context object. ### Setting Up Context with DataLoader ```ts const yoga = createYoga({ schema, context: async ({ request }) => { const token = request.headers.get('authorization')?.replace('Bearer ', ''); const currentUser = token ? await verifyToken(token) : null; return { db, currentUser, loaders: createLoaders(db), }; }, }); ``` --- ## Authentication and Authorization ### Context-Based Authentication Extract the user from the request headers and put them in context: ```ts context: async ({ request }) => { const token = request.headers.get('authorization')?.replace('Bearer ', ''); let currentUser: User | null = null; if (token) { try { const payload = jwt.verify(token, process.env.JWT_SECRET!); currentUser = await db.users.findById(payload.sub as string); } catch { // Invalid token — user stays null } } return { db, currentUser, loaders: createLoaders(db) }; }, ``` ### Resolver-Level Authorization ```ts const resolvers = { Mutation: { createPost: async (_parent: unknown, args: { input: CreatePostInput }, ctx: Context) => { if (!ctx.currentUser) { throw new GraphQLError('You must be logged in to create a post', { extensions: { code: 'UNAUTHENTICATED' }, }); } return ctx.db.posts.create({ ...args.input, authorId: ctx.currentUser.id }); }, deleteUser: async (_parent: unknown, args: { id: string }, ctx: Context) => { if (!ctx.currentUser) { throw new GraphQLError('Not authenticated', { extensions: { code: 'UNAUTHENTICATED' }, }); } if (ctx.currentUser.role !== 'ADMIN') { throw new GraphQLError('Admin access required', { extensions: { code: 'FORBIDDEN' }, }); } return ctx.db.users.delete(args.id); }, }, }; ``` ### Reusable Auth Helper ```ts function requireAuth(ctx: Context): User { if (!ctx.currentUser) { throw new GraphQLError('Authentication required', { extensions: { code: 'UNAUTHENTICATED' }, }); } return ctx.currentUser; } function requireRole(ctx: Context, role: Role): User { const user = requireAuth(ctx); if (user.role !== role) { throw new GraphQLError(`${role} access required`, { extensions: { code: 'FORBIDDEN' }, }); } return user; } // Usage in resolvers createPost: async (_parent, args, ctx) => { const user = requireAuth(ctx); return ctx.db.posts.create({ ...args.input, authorId: user.id }); }, ``` --- ## Pagination Patterns ### Offset-Based Pagination Simple and familiar: ```graphql type Query { posts(limit: Int = 20, offset: Int = 0): [Post!]! } ``` ```graphql query { posts(limit: 10, offset: 0) { title } # Page 1 posts(limit: 10, offset: 10) { title } # Page 2 posts(limit: 10, offset: 20) { title } # Page 3 } ``` **Pros:** Simple, supports "jump to page 5." **Cons:** Slow for large offsets (database scans), inconsistent results when data changes between pages. ### Cursor-Based Pagination (Relay-Style Connections) The industry standard for GraphQL pagination: ```graphql type Query { posts(first: Int, after: String, last: Int, before: String): PostConnection! } type PostConnection { edges: [PostEdge!]! pageInfo: PageInfo! totalCount: Int! } type PostEdge { cursor: String! node: Post! } type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String } ``` Usage: ```graphql # First page query { posts(first: 10) { edges { cursor node { title } } pageInfo { hasNextPage endCursor } } } # Next page (using endCursor from previous response) query { posts(first: 10, after: "abc123") { edges { cursor node { title } } pageInfo { hasNextPage endCursor } } } ``` ### TypeScript Resolver for Cursor Pagination ```ts posts: async (_parent: unknown, args: PaginationArgs, ctx: Context) => { const { first = 20, after } = args; let query = ctx.db.posts.query().orderBy('createdAt', 'desc').limit(first + 1); if (after) { const cursor = decodeCursor(after); query = query.where('createdAt', '<', cursor.createdAt); } const posts = await query.execute(); const hasNextPage = posts.length > first; const edges = posts.slice(0, first).map((post) => ({ cursor: encodeCursor({ createdAt: post.createdAt, id: post.id }), node: post, })); return { edges, pageInfo: { hasNextPage, hasPreviousPage: !!after, startCursor: edges[0]?.cursor ?? null, endCursor: edges[edges.length - 1]?.cursor ?? null, }, }; }, ``` The trick: fetch `first + 1` records. If you get more than `first`, there's a next page. Return only `first` records. ### When to Use Which | Pattern | Use When | |---------|----------| | **Offset** | Admin dashboards, internal tools, small datasets | | **Cursor** | Public APIs, infinite scroll, large datasets, real-time data | --- ## Error Handling ### GraphQL Error Format GraphQL returns errors alongside data, not instead of it: ```json { "data": { "user": { "name": "Ray" }, "deletedPost": null }, "errors": [ { "message": "Post not found", "locations": [{ "line": 5, "column": 3 }], "path": ["deletedPost"], "extensions": { "code": "NOT_FOUND" } } ] } ``` This is **partial success** — the user query succeeded, but the deletePost failed. The client can handle each independently. ### Union-Based Error Types (The Result Pattern) Instead of relying on the error array, encode errors in the type system: ```graphql type CreatePostSuccess { post: Post! } type ValidationError { field: String! message: String! } type NotAuthenticatedError { message: String! } union CreatePostResult = CreatePostSuccess | ValidationError | NotAuthenticatedError type Mutation { createPost(input: CreatePostInput!): CreatePostResult! } ``` Client usage: ```graphql mutation { createPost(input: { title: "", body: "content" }) { ... on CreatePostSuccess { post { id title } } ... on ValidationError { field message } ... on NotAuthenticatedError { message } } } ``` This pattern makes errors **typed and discoverable** — clients can see all possible error states in the schema, and there's no guessing about error shapes. --- ## Caching Strategies ### Client-Side: Normalized Caching Apollo Client and urql use **normalized caching** — they store entities by type and ID, not by query. When a mutation updates a `Post`, every query that references that post automatically gets the updated data. ``` Cache: User:123 → { id: "123", name: "Ray", ... } Post:456 → { id: "456", title: "GraphQL Deep Dive", author: { __ref: "User:123" } } Post:789 → { id: "789", title: "TypeScript Generics", author: { __ref: "User:123" } } Query "GetUser(123)" → resolves from cache using User:123 + linked Post refs ``` This is why GraphQL clients can feel "instant" — after the first fetch, subsequent reads often resolve from cache without a network request. ### Persisted Queries for CDN Caching Normal GraphQL queries are POST requests with a body, which CDNs can't cache. **Persisted queries** solve this: 1. At build time, extract all queries and assign each a hash 2. Send the hash instead of the full query: `GET /graphql?extensions={"persistedQuery":{"sha256Hash":"abc123"}}` 3. CDN can cache GET responses by hash ### Server-Side Caching with Redis ```ts import Redis from 'ioredis'; const redis = new Redis(); const resolvers = { Query: { popularPosts: async (_parent: unknown, _args: unknown, ctx: Context) => { const cacheKey = 'popular-posts'; const cached = await redis.get(cacheKey); if (cached) { return JSON.parse(cached); } const posts = await ctx.db.posts.findPopular(20); await redis.set(cacheKey, JSON.stringify(posts), 'EX', 300); // 5 min TTL return posts; }, }, }; ``` --- ## Performance and Security ### Query Complexity Analysis Malicious or careless clients can send expensive queries: ```graphql query Expensive { users(limit: 1000) { posts(limit: 100) { comments(limit: 100) { author { posts(limit: 100) { comments(limit: 100) { # ... deeply nested } } } } } } } ``` **Depth limiting** rejects queries that exceed a maximum nesting level: ```ts import { createYoga } from 'graphql-yoga'; import { useDepthLimit } from '@envelop/depth-limit'; const yoga = createYoga({ schema, plugins: [useDepthLimit({ maxDepth: 10 })], }); ``` **Complexity analysis** assigns a cost to each field and rejects queries that exceed a budget: ```ts import { useQueryComplexity } from '@envelop/query-complexity'; const yoga = createYoga({ schema, plugins: [ useQueryComplexity({ maximumComplexity: 1000, estimators: [ simpleEstimator({ defaultComplexity: 1 }), fieldExtensionsEstimator(), ], }), ], }); ``` ### Disable Introspection in Production Introspection lets clients discover the schema. Useful in development, a security risk in production: ```ts const yoga = createYoga({ schema, graphiql: process.env.NODE_ENV !== 'production', maskedErrors: process.env.NODE_ENV === 'production', }); ``` ### Rate Limiting Apply per-user rate limits to prevent abuse: ```ts const rateLimitMap = new Map(); function checkRateLimit(userId: string, maxRequests: number, windowMs: number): void { const now = Date.now(); const record = rateLimitMap.get(userId); if (!record || now > record.resetAt) { rateLimitMap.set(userId, { count: 1, resetAt: now + windowMs }); return; } if (record.count >= maxRequests) { throw new GraphQLError('Rate limit exceeded', { extensions: { code: 'RATE_LIMITED' }, }); } record.count++; } ``` --- ## Schema Design Best Practices ### Think in Graphs, Not Endpoints REST designs around resources and actions. GraphQL designs around **relationships**: ```graphql # BAD — REST-style thinking type Query { getUserPosts(userId: ID!): [Post!]! getPostComments(postId: ID!): [Comment!]! } # GOOD — graph thinking type Query { user(id: ID!): User post(id: ID!): Post } type User { posts: [Post!]! # Navigate from user to their posts } type Post { author: User! # Navigate from post to its author comments: [Comment!]! # Navigate from post to its comments } ``` In the graph approach, clients traverse relationships naturally. Need a user's posts? Query the user and expand `posts`. Need a post's author? Expand `author`. The schema models the domain as a connected graph. ### Naming Conventions ```graphql # Types: PascalCase type UserProfile { ... } # Fields: camelCase type User { firstName: String! createdAt: DateTime! } # Enums: SCREAMING_SNAKE_CASE enum PostStatus { DRAFT PUBLISHED ARCHIVED } # Input types: PascalCase with Input suffix input CreateUserInput { ... } input UpdateUserInput { ... } # Mutations: verb + noun type Mutation { createUser(input: CreateUserInput!): User! updateUser(id: ID!, input: UpdateUserInput!): User! deleteUser(id: ID!): Boolean! publishPost(id: ID!): Post! } ``` ### Evolving Schemas Without Breaking Clients GraphQL doesn't use URL versioning. Instead: 1. **Add fields freely** — adding new fields never breaks existing queries 2. **Deprecate before removing** — mark fields with `@deprecated(reason: "Use 'name' instead")` 3. **Never change field types** — if `name` is `String`, it can't become `Name` object 4. **Never make nullable fields non-null** — clients might not handle the change ```graphql type User { fullName: String! @deprecated(reason: "Use 'firstName' and 'lastName' instead") firstName: String! lastName: String! } ``` --- ## GraphQL with TypeScript End-to-End The ultimate goal: **full-stack type safety** where the schema drives types for both server and client. ### The Pipeline ``` Schema (SDL) → Code Generator → TypeScript types → Used in resolvers AND client queries ``` ### GraphQL Code Generator Setup ```bash npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-resolvers @graphql-codegen/typescript-operations ``` ```yaml # codegen.yml schema: './src/schema/**/*.graphql' documents: './src/client/**/*.graphql' generates: ./src/generated/types.ts: plugins: - typescript - typescript-resolvers config: contextType: '../context#Context' mappers: User: '../models#UserModel' Post: '../models#PostModel' ./src/generated/operations.ts: plugins: - typescript - typescript-operations ``` Run codegen: ```bash npx graphql-codegen ``` Now resolvers are type-checked against the schema. If you add a field to the schema, TypeScript tells you that a resolver is missing. If you query a field that doesn't exist, the client code won't compile. ### gql.tada (Zero-Config Type Safety) A newer approach that infers types directly from tagged template literals: ```ts import { graphql } from 'gql.tada'; const GetUserQuery = graphql(` query GetUser($id: ID!) { user(id: $id) { id name posts { title } } } `); // ResultOf is automatically inferred // { user: { id: string; name: string; posts: { title: string }[] } | null } ``` No codegen step. Types are inferred at compile time from the schema. This is the direction the ecosystem is moving. --- ## GraphQL in the Real World ### Who Uses GraphQL - **GitHub** — Their entire v4 API is GraphQL. REST v3 is in maintenance mode. - **Shopify** — Storefront API and Admin API are both GraphQL. - **Spotify** — Powers their Backstage developer portal. - **Airbnb** — Migrated from REST to GraphQL for their mobile clients. - **The New York Times** — Content delivery for multiple platforms. ### When NOT to Use GraphQL - **Simple CRUD APIs** — If every client needs the same data, REST is simpler. - **File uploads** — GraphQL wasn't designed for binary data. Use REST for uploads and GraphQL for metadata. - **Microservices without a gateway** — GraphQL shines as a unifying layer, not as internal communication between services. - **When HTTP caching is critical** — REST's GET-based caching is hard to replicate with GraphQL's POST requests. - **Tiny teams with simple needs** — The overhead of schema design, resolvers, DataLoaders, and codegen may not be justified. ### The BFF Pattern (Backend for Frontend) A common architecture: use GraphQL as a **Backend for Frontend** that aggregates data from multiple REST/gRPC microservices: ``` Mobile App ─┐ ├──→ GraphQL BFF ──→ User Service (REST) Web App ──┤ ──→ Post Service (gRPC) │ ──→ Notification Service (REST) Admin Tool ──┘ ──→ Analytics Service (REST) ``` Each client queries the GraphQL BFF for exactly the data it needs. The BFF resolvers fan out to the underlying services. This decouples frontend development from backend service design. --- ## Common Pitfalls ### Pitfall 1: N+1 Without DataLoader Every nested field resolver that makes a database call without batching is an N+1 bug waiting to happen. Always use DataLoader for fields that resolve by loading from a data source. ### Pitfall 2: Exposing Introspection in Production Introspection reveals your entire schema. Disable it in production or use persisted queries to prevent arbitrary queries. ### Pitfall 3: No Depth or Complexity Limits Without limits, a single malicious query can bring your server to its knees. Always set a maximum query depth and complexity budget. ### Pitfall 4: Over-Engineering the Schema ```graphql # BAD — premature abstraction type Query { entity(type: EntityType!, id: ID!): Entity } # GOOD — explicit and discoverable type Query { user(id: ID!): User post(id: ID!): Post } ``` Start specific. Generalize only when you have a real need. ### Pitfall 5: Returning Large Lists Without Pagination ```graphql # BAD — returns all posts in the database type Query { posts: [Post!]! } # GOOD — paginated type Query { posts(first: Int = 20, after: String): PostConnection! } ``` Always paginate list fields. Even if the dataset is small now, it won't stay that way. --- ## Cheat Sheet ### SDL Quick Reference ```graphql # Scalars scalar DateTime # Enums enum Status { ACTIVE INACTIVE } # Types type User { id: ID! # Non-null ID name: String! # Non-null string bio: String # Nullable string posts: [Post!]! # Non-null list of non-null posts status: Status! # Enum field } # Input types input CreateUserInput { name: String! email: String! } # Interfaces interface Node { id: ID! } # Unions union SearchResult = User | Post # Root types type Query { user(id: ID!): User } type Mutation { createUser(input: CreateUserInput!): User! } type Subscription { userCreated: User! } ``` ### Resolver Signature ```ts (parent: ParentType, args: ArgsType, context: ContextType, info: GraphQLResolveInfo) => ReturnType ``` ### Common Patterns | Pattern | When to Use | |---------|-------------| | DataLoader | Any nested field that fetches from a data source | | Cursor pagination | List fields in public APIs | | Union error types | When clients need typed error handling | | Context auth | Every authenticated GraphQL API | | Persisted queries | Production APIs exposed to the internet | | Depth limiting | Every production GraphQL server | ### Decision: REST vs GraphQL ``` Is the API consumed by multiple clients with different data needs? ├── YES → GraphQL is a strong fit └── NO → Is the data model deeply nested with many relationships? ├── YES → GraphQL └── NO → REST is simpler and probably sufficient ``` --- ## What's Next GraphQL sits at the intersection of API design, type systems, and data fetching. To go deeper: - **PostgreSQL: The Complete Deep Dive** covers the database layer that your resolvers talk to. - **System Design: The Complete Deep Dive** explains caching, load balancing, and microservice architectures that GraphQL APIs operate within. - **TypeScript Generics: The Complete Deep Dive** covers the type-level programming that powers codegen and typed resolvers. GraphQL isn't the right tool for every API, but when it fits — complex data relationships, multiple clients, strong typing — it's transformative. The key is understanding both its strengths and its trade-offs, and now you have the knowledge to make that call with confidence.

GraphQL: The Complete Deep Dive