Data & APIs in depth
Design and build the endpoint that powers your own interface.
Phase 3 · Full stack · 8 sections · about 9 minutes
Promise
An endpoint is a contract. Your UI talks to your backend by sending a request: here's the data, here's what I want you to do. The backend sends back a response: here's the result, or here's what went wrong. The contract is explicit, both sides know the shape of the request, the shape of the response, and what can fail.
In this module, you'll stop treating endpoints like magic and start designing them like a real software engineer. You'll build a working API endpoint that handles a real feature (a waitlist form, a note-saving UI, a to-do adder) and learn the patterns that keep endpoints reliable: validation, error handling, and the difference between the three ways Next.js lets you talk to servers.
By the end, you'll have deployed an endpoint that validates input, talks to a database, and reports errors clearly. You'll understand HTTP well enough to debug it. And you'll know which Next.js pattern to reach for in any situation.
Concepts
1. What a request really is
When your browser sends a request, it's not magic. It's structured data: a verb, a path, optional headers, optional body.
POST /api/waitlist HTTP/1.1Host: example.comContent-Type: application/json { "email": "alice@example.com"}Breaking this down:
- Verb: POST. Tells the server "I want you to create something." (GET = read, POST = create, PUT = update, DELETE = delete)
- Path:
/api/waitlist. The thing you want to do. - Headers: metadata about the request.
Content-Type: application/jsonmeans "the body is JSON." - Body: the actual payload, the email address, in this case.
The server responds:
HTTP/1.1 201 CreatedContent-Type: application/json { "success": true, "id": "waitlist_abc123"}- Status code: 201 means "I created it." 200 = success (no create), 400 = bad input, 500 = server error.
- Response body: what happened. Could be success, could be an error message.
This is everything. A POST with no body is a request. A GET with 20 headers is a request. An image is a request (it returns binary instead of JSON). The language doesn't matter, a request is a request, whether it's coming from a browser, an app, or curl.
# This is the same request, from the command line:curl -X POST https://example.com/api/waitlist \ -H "Content-Type: application/json" \ -d '{"email":"alice@example.com"}'2. Route handlers, the Next.js way
Next.js gives you a file-based router for API endpoints. A file at app/api/waitlist/route.ts handles requests to /api/waitlist.
// app/api/waitlist/route.tsexport async function POST(request: Request) { // 1. Parse the incoming request const body = await request.json(); const email = body.email; // 2. Validate the input if (!email || !email.includes("@")) { return Response.json({ error: "Invalid email" }, { status: 400 }); } // 3. Do something (save to database, send email, etc.) // For now, just pretend: const id = Math.random().toString(36).slice(2, 9); // 4. Respond with success return Response.json({ success: true, id }, { status: 201 });}Every route handler is an async function named after the HTTP verb it handles. POST, GET, PUT, DELETE. The function receives the Request, does work, and returns a Response.
Multiple verbs on the same route:
// Handles both GET /api/notes and POST /api/notesexport async function GET(request: Request) { return Response.json({ notes: [] });} export async function POST(request: Request) { const body = await request.json(); // save it return Response.json({ id: "note_123" }, { status: 201 });}The status code matters. Use:
200(default): success, no creation201: success, created something400: client error (bad input)401: unauthorized (not logged in)404: not found500: server error (your code broke)
3. Server actions, the React way
Server actions are a shortcut. Instead of writing a route handler, you write a function marked 'use server' that lives inside your component or in a shared file. When you call it from the browser, Next.js automatically sends it to the server and runs it there.
// actions/saveNote.ts"use server"; export async function saveNote(title: string, body: string) { // This code runs on the server only. // Validate the input if (!title || title.trim().length === 0) { throw new Error("Title is required"); } // Save to database (pretend) const id = Math.random().toString(36).slice(2, 9); return { id };}Call it from a client component:
// components/NoteForm.tsx'use client'; import { saveNote } from '@/actions/saveNote'; export default function NoteForm() { async function handleSubmit(formData: FormData) { const title = formData.get('title') as string; const body = formData.get('body') as string; try { const result = await saveNote(title, body); console.log('Saved:', result.id); } catch (error) { console.error('Failed:', error.message); } } return ( <form action={handleSubmit}> <input name="title" placeholder="Title" required /> <textarea name="body" placeholder="Body" required /> <button type="submit">Save</button> </form> );}Server actions are simpler than route handlers for straightforward cases (form submission, single operation). But they're less flexible, you can't set custom status codes, you can't handle different HTTP verbs cleanly, and testing them is harder. Use route handlers when you need control; use server actions when you want simplicity.
4. Validation, the most important part
Never trust user input. Ever. Your API is a public door. Anyone can send anything.
export async function POST(request: Request) { const body = await request.json(); // Attacker sends: { email: null, count: "DROP TABLE users;", user_id: 12345 } // Without validation, you're in trouble. // Validate each field: if (typeof body.email !== "string" || !body.email.includes("@")) { return Response.json( { error: "email must be a valid email address" }, { status: 400 }, ); } if (typeof body.count !== "number" || body.count < 0) { return Response.json( { error: "count must be a positive number" }, { status: 400 }, ); } // Now you can use body.email and body.count safely.}For larger schemas, use a validation library like Zod:
import { z } from "zod"; const WaitlistSchema = z.object({ email: z.string().email("Invalid email address"), name: z.string().min(1, "Name is required").max(100), referral: z.string().optional(),}); export async function POST(request: Request) { const body = await request.json(); // If validation fails, Zod throws an error with details const parsed = WaitlistSchema.parse(body); // parsed.email, parsed.name, parsed.referral are now type-safe // and you know they meet the schema.}Wrap it in a try-catch to catch validation errors:
export async function POST(request: Request) { try { const body = await request.json(); const parsed = WaitlistSchema.parse(body); // Save to database const id = await db.waitlist.create(parsed); return Response.json({ id }, { status: 201 }); } catch (error) { if (error instanceof z.ZodError) { return Response.json( { error: "Validation failed", details: error.issues }, { status: 400 }, ); } console.error("Unexpected error:", error); return Response.json({ error: "Something went wrong" }, { status: 500 }); }}The rule: validate early, fail fast, report clearly.
Build: A working endpoint
You're going to build a real endpoint that saves email addresses to a waitlist. The UI will be a form; the backend will validate the email and respond with success or an error.
Step 1: Create the route handler
Create app/api/waitlist/route.ts:
import { z } from "zod"; const EmailSchema = z.object({ email: z.string().email("Invalid email address"),}); export async function POST(request: Request) { try { const body = await request.json(); const { email } = EmailSchema.parse(body); // For now, just pretend we saved it. In Databases & ORM you'll use a real database. // Simulate a random ID like a database would generate const id = Math.random().toString(36).slice(2, 9); // Simulate a small delay (like a database write would take) await new Promise((resolve) => setTimeout(resolve, 200)); return Response.json( { success: true, id, message: `Added ${email} to the waitlist`, }, { status: 201 }, ); } catch (error) { if (error instanceof z.ZodError) { return Response.json( { error: "Validation failed", details: error.issues }, { status: 400 }, ); } if (error instanceof SyntaxError) { return Response.json({ error: "Invalid JSON" }, { status: 400 }); } console.error("Unexpected error:", error); return Response.json({ error: "Something went wrong" }, { status: 500 }); }} export async function GET() { return Response.json({ message: "POST your email to join the waitlist", });}Step 2: Create the form component
Create components/WaitlistForm.tsx:
'use client'; import { useState } from 'react'; export default function WaitlistForm() { const [email, setEmail] = useState(''); const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle'); const [message, setMessage] = useState(''); async function handleSubmit(e: React.FormEvent) { e.preventDefault(); setStatus('loading'); setMessage(''); try { const response = await fetch('/api/waitlist', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email }), }); const data = await response.json(); if (!response.ok) { setStatus('error'); setMessage(data.error || 'Something went wrong'); return; } setStatus('success'); setMessage(data.message); setEmail(''); } catch (error) { setStatus('error'); setMessage('Network error. Try again.'); } } return ( <form onSubmit={handleSubmit} className="space-y-4"> <div> <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} placeholder="your@email.com" required className="w-full px-4 py-2 border rounded" disabled={status === 'loading'} /> </div> <button type="submit" disabled={status === 'loading'} className="w-full px-4 py-2 bg-blue-600 text-white rounded disabled:opacity-50" > {status === 'loading' ? 'Adding...' : 'Join Waitlist'} </button> {message && ( <p className={status === 'success' ? 'text-green-600' : 'text-red-600'}> {message} </p> )} </form> );}Step 3: Add the form to a page
In any page (e.g., app/page.tsx), import and use it:
import WaitlistForm from '@/components/WaitlistForm'; export default function Home() { return ( <div className="max-w-md mx-auto mt-20"> <h1 className="text-3xl font-bold mb-8">Join our waitlist</h1> <WaitlistForm /> </div> );}Step 4: Test it
Run npm run dev and open http://localhost:3000. Try:
- 1Valid email:
alice@example.com→ should show "Added alice@example.com to the waitlist" - 2Invalid email:
notanemail→ should show "Validation failed" - 3Empty field: → HTML validation prevents submit
- 4Network error: Open DevTools, go to Network tab, throttle to offline, try submitting → should show "Network error"
Patterns & Examples
Error handling
Always distinguish between client errors (400) and server errors (500):
export async function POST(request: Request) { try { const body = await request.json(); // ... validation ... // Simulating a database call const result = await saveToDatabase(body); return Response.json(result, { status: 201 }); } catch (error) { // Client error: bad input if (error instanceof ValidationError) { return Response.json({ error: error.message }, { status: 400 }); } // Server error: something broke console.error("Database error:", error); return Response.json( { error: "Failed to save. Try again later." }, { status: 500 }, ); }}Query parameters
For GET requests, parameters come from the URL:
export async function GET( request: Request, { params }: { params: { id: string } },) { // /api/notes/123 → params.id = '123' // Query string: /api/notes?limit=10&sort=date const { searchParams } = new URL(request.url); const limit = searchParams.get("limit") ?? "20"; const sort = searchParams.get("sort") ?? "date"; return Response.json({ limit, sort, });}Dynamic routes
For a route like /api/notes/[id]/route.ts:
export async function GET( request: Request, { params }: { params: { id: string } },) { const { id } = params; // Validate the ID (is it a number? is it the right format?) if (!/^\d+$/.test(id)) { return Response.json({ error: "Invalid note ID" }, { status: 400 }); } // Fetch from database const note = { id, title: "Example note" }; return Response.json(note);} export async function PUT( request: Request, { params }: { params: { id: string } },) { const { id } = params; const body = await request.json(); // Update the note return Response.json({ success: true });} export async function DELETE( request: Request, { params }: { params: { id: string } },) { const { id } = params; // Delete the note return Response.json({ success: true });}Middleware: authentication
Before handling a request, check if the user is logged in:
// app/api/notes/route.tsimport { getSession } from "@/lib/auth"; // pretend function export async function POST(request: Request) { // Check auth first const session = await getSession(request); if (!session) { return Response.json({ error: "Not authenticated" }, { status: 401 }); } // Now you know the user is logged in const body = await request.json(); // ... rest of handler}Checkpoint
Build a working endpoint for one of these features:
Option A: Waitlist (simplest)
- Endpoint: POST
/api/waitlist - Accepts:
{ email: string } - Validates: email is a valid email address
- Returns:
{ success: true, id: string }on success, or{ error: string }on failure - Status codes: 201 on success, 400 on validation error, 500 on server error
- Form: text input for email, submit button, shows success message or error
Test:
- Valid email → shows success
- Invalid email → shows validation error
- Clicking while loading → button is disabled
Option B: Note saver (more realistic)
- Endpoint: POST
/api/notes - Accepts:
{ title: string, body: string, tags?: string[] } - Validates: title is 1–100 characters, body is 1–10000 characters, tags are strings
- Returns:
{ success: true, id: string }with the note ID - Endpoint: GET
/api/notesreturns list of saved notes - Form: text input for title, textarea for body, tags field, submit button
Test:
- Empty title → error
- Long title (>100 chars) → error
- Valid note → saved and displayed in list
- Multiple saves → each gets unique ID
Option C: To-do adder (with delete)
- Endpoint: POST
/api/todos - Accepts:
{ text: string, priority: 'low' | 'medium' | 'high' } - Validates: text is 1–200 characters, priority is one of the three values
- Returns: the created to-do with ID
- Endpoint: DELETE
/api/todos/[id] - Form: text input, priority dropdown, add button, shows list of to-dos with delete button on each
Test:
- Empty text → error
- Invalid priority → error
- Add multiple to-dos → all appear in list
- Delete a to-do → removed from list
Requirements (all options)
Testing checklist
# Test the endpoint manually with curl: # Valid request:curl -X POST http://localhost:3000/api/waitlist \ -H "Content-Type: application/json" \ -d '{"email":"alice@example.com"}' # Invalid request:curl -X POST http://localhost:3000/api/waitlist \ -H "Content-Type: application/json" \ -d '{"email":"notanemail"}' # Malformed JSON:curl -X POST http://localhost:3000/api/waitlist \ -H "Content-Type: application/json" \ -d 'this is not json'Each should return the correct status code and error message.
Why HTTP outlives the framework
The protocol is not the framework
An HTTP endpoint is a language-agnostic contract. You can write an endpoint in Node, Python, Go, Rust, the protocol is the same. A POST request is a POST request. A 400 status code means the same thing everywhere.
Next.js provides the framework (route handlers, Response API, server actions), but you need to understand the language (HTTP) first. If you learn Next.js without learning HTTP, you'll hit a wall the moment you need to integrate with a third-party API, debug a network issue, or switch frameworks.
In this module, the framework is Next.js. But the concept is HTTP. Write the POST handler so well that you could rewrite it in Flask (Python) and it would behave identically. That's the difference between learning a tool and learning to think like an engineer.
Question: Can you rewrite your waitlist endpoint in a different language without changing the contract (same inputs, same outputs, same status codes)? Try it in your mind. That's how you know you've learned the pattern, not just the syntax.
What the platform hands you
Next.js gives you Request and Response objects from the web standard. They come from the platform (the browser API, the Node.js runtime). You're not writing framework-specific code, you're writing platform-standard code.
This has a huge upside: your endpoint code is portable. The Response.json() method works the same way in Next.js, in a Worker, in a Node.js HTTP server. But it also means you need to understand what the platform gives you, not just how Next.js wraps it.
Study the Request object. It has .json(), .text(), .blob(), .formData(). Each parses the body differently. It has a .url property (a string), which you can wrap in new URL() to extract query parameters. It has headers. Understand these, and you'll be able to debug a request-handling problem in seconds instead of an hour.
Same with Response. You could construct it manually: new Response(JSON.stringify(data), { status: 201, headers: ... }). Or use the shortcut Response.json(). Both are valid. The shortcut is usually better, but know the underlying platform.
Question: What happens if you forget to await request.json()? Try it. The request body is a stream, you have to explicitly consume it. That's the platform. It's not a Next.js quirk. Understanding that distinction will save you.
Key takeaways
- 1An HTTP request is a contract. Verb, path, headers, body. Verb tells you what the client wants (GET = read, POST = create, etc.). Status code tells the client what happened (201 = created, 400 = bad input, 500 = error).
- 1Validate every input. Use Zod or similar. Never assume the shape of the data.
- 1Choose the right tool. Route handlers for flexibility and control. Server actions for simplicity on one-off forms.
- 1Fail fast and fail clearly. Validate early, throw early, catch errors and respond with a meaningful message.
- 1Understand the platform.
RequestandResponseare web standards. Learn them, and you'll be able to work in any framework.
- 1Test it manually. Open curl. Hit your endpoint. See what it returns. That's how you'll debug 90% of your API problems.