Build a GraphQL API

Overview

You're going to build a GraphQL API for a book review platform. Users can query books, authors, and reviews, add new books, and submit reviews with ratings. The API features schema-first design, TypeScript resolvers, input validation, custom error handling, and a playground for testing.

GraphQL solves real problems that REST introduces: over-fetching (getting 50 fields when you need 3), under-fetching (making 5 requests to assemble one view), and the constant API versioning dance. By the end of this tutorial, you'll understand when GraphQL is the right tool and how to build it properly.

You'll use Apollo Server 4, TypeScript, and Zod for input validation. No database — we'll use an in-memory store so you can focus entirely on the GraphQL layer.

Step 1: Project Setup

Create the source directory:

Add a start script to package.json:

Step 2: Define the Schema

Schema-first means you design your API contract before writing any resolver logic.

Notice the ! suffix means non-nullable. [Book!]! means the array itself is non-null AND every element in it is non-null. This is a contract — the client knows exactly what it will receive.

Step 3: In-Memory Data Store

Step 4: Input Validation with Zod

Validate inputs before they reach your data layer.

Step 5: Query Resolvers

Resolvers map schema fields to data. Field resolvers on types handle relationships.

Step 6: Type Resolvers for Relationships

These resolve the author field on Book, the books field on Author, and so on.

This is the power of GraphQL. When a client queries { books { title author { name } } }, the Book.author resolver runs only if the client requested the author field. No wasted computation.

Step 7: Mutation Resolvers

Step 8: Error Handling and Formatting

GraphQL has a standardized error format. Apollo Server lets you customize error responses.

This ensures validation errors and not-found errors are returned to the client with useful details, but unexpected errors (database failures, null pointer exceptions) are masked to prevent information leakage.

Step 9: Server Entry Point

Step 10: Testing with the Playground

Start the server with npm run dev and open http://localhost:4000 in your browser. Apollo Server 4 includes Apollo Sandbox for testing queries.

Try a nested query to see GraphQL's power:

This single request replaces what would be 3-4 REST calls: one for books, one for each author, and one for reviews per book. The client declares exactly what shape of data it needs, and the server resolves it in a single round trip.

Test a mutation:

The response includes the newly created review AND the updated average rating for the book — all in one request. Test error handling by submitting a rating of 6 or a non-existent book ID and inspect the structured error response with field-level validation messages.

Overview

You'll use Apollo Server 4, TypeScript, and Zod for input validation. No database — we'll use an in-memory store so you can focus entirely on the GraphQL layer.

Step 10: Testing with the Playground

Start the server with npm run dev and open http://localhost:4000 in your browser. Apollo Server 4 includes Apollo Sandbox for testing queries.

Try a nested query to see GraphQL's power:

Test a mutation:

// src/data/store.ts export interface BookRecord { id: string; title: string; description: string; isbn: string; publishedYear: number; authorId: string; } export interface AuthorRecord { id: string; name: string; bio: string | null; } export interface ReviewRecord { id: string; bookId: string; rating: number; comment: string; createdAt: string; } let nextId = 100; function generateId(): string { return String(++nextId); } const authors: AuthorRecord[] = [ { id: "1", name: "Octavia Butler", bio: "American science fiction author." }, { id: "2", name: "Ted Chiang", bio: "American science fiction writer." }, { id: "3", name: "Ursula K. Le Guin", bio: null }, ]; const books: BookRecord[] = [ { id: "1", title: "Kindred", description: "A time-travel novel about slavery.", isbn: "978-0807083697", publishedYear: 1979, authorId: "1", }, { id: "2", title: "Stories of Your Life and Others", description: "A collection of short stories.", isbn: "978-1101972120", publishedYear: 2002, authorId: "2", }, { id: "3", title: "The Left Hand of Darkness", description: "A sci-fi novel exploring gender.", isbn: "978-0441478125", publishedYear: 1969, authorId: "3", }, ]; const reviews: ReviewRecord[] = [ { id: "1", bookId: "1", rating: 5, comment: "A masterpiece of American fiction.", createdAt: "2024-01-15T10:00:00Z", }, { id: "2", bookId: "1", rating: 4, comment: "Powerful and uncomfortable in the best way.", createdAt: "2024-02-20T14:30:00Z", }, ]; export const store = { authors: { getAll: (): AuthorRecord[] => authors, getById: (id: string): AuthorRecord | undefined => authors.find((a) => a.id === id), }, books: { getAll: (limit?: number, offset?: number): BookRecord[] => { const start = offset ?? 0; const end = limit ? start + limit : undefined; return books.slice(start, end); }, getById: (id: string): BookRecord | undefined => books.find((b) => b.id === id), getByAuthor: (authorId: string): BookRecord[] => books.filter((b) => b.authorId === authorId), search: (query: string): BookRecord[] => { const lower = query.toLowerCase(); return books.filter( (b) => b.title.toLowerCase().includes(lower) || b.description.toLowerCase().includes(lower) ); }, create: (input: Omit<BookRecord, "id">): BookRecord => { const book: BookRecord = { ...input, id: generateId() }; books.push(book); return book; }, delete: (id: string): boolean => { const index = books.findIndex((b) => b.id === id); if (index === -1) return false; books.splice(index, 1); return true; }, }, reviews: { getByBook: (bookId: string): ReviewRecord[] => reviews.filter((r) => r.bookId === bookId), create: (input: Omit<ReviewRecord, "id" | "createdAt">): ReviewRecord => { const review: ReviewRecord = { ...input, id: generateId(), createdAt: new Date().toISOString(), }; reviews.push(review); return review; }, }, };