Servers and Backends
Your code running on someone else's request - routes, handlers and honest status codes.
Before this: Shipping Your First App
Objective
Run a backend server locally, explain how routes map to handler functions, and expose a real JSON API that answers with correct status codes.
Vocabulary
The words to use when directing your agent.
- server
- A long-running program that listens for requests and sends responses.
- route
- The pairing of an HTTP method and URL path with the function that handles it.
- handler
- The function that runs when a request hits its route.
- port
- The numbered door on a machine where a server listens, like 3000.
- request method
- The verb of a request - GET reads, POST creates, PUT/PATCH updates, DELETE removes.
Understand it
Status codes are your API's body language
200 created-or-found, 400 you sent garbage, 401 you are not logged in, 403 you may not, 404 no such thing, 500 I broke. An API that returns 200 for everything - including failures - is lying to every client that trusts it.
Why backends hold the power
Frontend code ships to strangers; backend code stays home. Secrets, real validation and database access live server-side precisely because nobody can tamper with what they cannot touch.
Core concepts
A server is just your program, listening
Strip the mystique: a backend is code that starts, binds to a port, and loops forever answering requests. You have run programs since Level 0; this one happens to answer the phone.
Routes are a switchboard
GET /expenses goes to listExpenses(), POST /expenses goes to createExpenses(). Same URL, different methods, different jobs. When you can enumerate an API's route table from memory, you understand the app's surface area.
Examples
One handler, dissected
POST /expenses receives JSON, validates amount is a positive number, asks the store layer to save, replies 201 with the saved record - or 400 naming exactly which field failed. Four steps, same skeleton as every handler you will ever review.
curl is your UI
curl http://localhost:3000/expenses exercises the API directly, bypassing any interface. Backend developers live in this mode because UIs hide what the API actually said.
Common mistakes
Common mistake
Verifying API behavior only through the app's screens.
Fix
Exercise endpoints directly with curl or an agent-run script; the screen is one consumer, not the contract.
Common mistake
Returning 200 with an error message inside the body.
Fix
Match status to outcome. Clients branch on codes; make them truthful.
Working with your AI agent
Require your agent to print the full route table at startup and provide a sample curl for each route in the README. A route table you can read is a surface you can defend and test.
Build it
The module’s real project. Your agent builds; you direct and inspect.
Project: Expense API
Rebuild the tracker's brain as a standalone HTTP API - no screens, pure endpoints - so every future module can build on a real, testable service.
Requirements
- Endpoints: GET /health, GET /expenses, POST /expenses, PUT /expenses/:id, DELETE /expenses/:id
- POST/PUT validate amount positive number and category required; violations return 400 naming the field
- Unknown routes return 404; DELETE on missing id returns 404
- README documents every route with a working curl example
- Data persists across server restarts using the store layer pattern from Level 1
Context for your agent
Build a minimal JSON API server for expenses: the five listed endpoints with correct status codes (200/201/400/404), server-side validation rejecting bad payloads with field-specific messages, persistent storage through a dedicated store layer, and a README route table with curl examples per endpoint. Print the route table at startup. No authentication yet - that arrives next module; keep handlers structured so auth middleware can slot in cleanly.
Verify it - twice
Check every item yourself first. Then hand your agent the prompt and compare verdicts.
Verification prompt - paste into your AI agent
Review my Expense API as a backend reviewer who does not trust documentation. Start the server yourself if possible. Verify PASS or FAIL with evidence: (1) all five routes exist and behave as documented, (2) malformed and rule-violating payloads return 400 with field-naming messages, (3) unknown routes and missing ids return clean 404s, (4) error responses share one consistent shape across all endpoints, (5) storage survives a restart, (6) handlers are thin with logic in a store layer. Then attack it with five hostile requests - wrong content types, huge payloads, negative numbers, missing fields - and report exactly how each was handled.
Run this against “Servers and Backends” after your own checklist pass. Where the agent and you disagree, investigate before moving on.
Review questions
Answer out loud. If you cannot, revisit before moving on.
Recite your API's route table from memory, method plus path plus purpose.
What should PUT /expenses/999 return if 999 does not exist, and why not 200?
Why does validation belong in the server even though the form already checks?
You can now
- Build and read a real JSON API's route table
- Demand truthful status codes from every endpoint
- Test backends directly instead of through screens
Up next
Relational Data Modeling