Frontend to Backend over HTTP

Goal

Trace a request from the browser to the backend, read it in the logs, and explain why the browser only ever talks to one origin.

What you'll learn

• How a static Next.js site talks to an API it does not host
• What a reverse proxy does, and why it removes the need for CORS
• The API contract: methods, status codes and the error shape
• Request ids and structured logs

Architecture

browser                     web container (nginx :8080)              backend container (:8000)
GET /app/          ──────►  /usr/share/nginx/html/app/index.html
fetch POST /api/ask ─────►  location /api/ → proxy_pass http://backend:8000 ─► FastAPI route /api/ask
                    ◄─────  same response, plus security headers   ◄─────────  JSON

The site is a static export (next build with output: 'export'): HTML, CSS and JavaScript files. No Node.js runs in production. The assistant page calls fetch('/api/...'), a path on the same origin, and nginx forwards it.

Prerequisites

Module 02, stack running.

Steps

1. Read the frontend's API client

Open frontend/src/lib/api.ts. Every call is fetch(${API_URL}/api${path}) and API_URL is empty in Docker. So the browser requests /api/notes from the same host and port that served the page.

2. Read the proxy rule

Open frontend/nginx.conf:

resolver 127.0.0.11 valid=10s ipv6=off;
set $backend http://backend:8000;

location /api/ {
    proxy_pass $backend;
    proxy_read_timeout 30s;
}

backend is a Compose service name. 127.0.0.11 is Docker's built-in DNS server (module 05).

3. Call the API the way the browser does

curl -s -i 'http://127.0.0.1:3000/api/notes?limit=1' | head -12

4. Create, read, update and delete

curl -s -X POST http://127.0.0.1:3000/api/notes \
  -H 'Content-Type: application/json' \
  -d '{"title":"Wi-Fi","body":"The guest network is called harbour-guest."}' -i | head -1
curl -s http://127.0.0.1:3000/api/notes/9999
curl -s -X POST http://127.0.0.1:3000/api/notes -H 'Content-Type: application/json' -d '{"title":""}'

HTTP/1.1 201 Created
{"error":{"code":"NOTE_NOT_FOUND","message":"Note 9999 does not exist."}}
{"error":{"code":"VALIDATION_FAILED","message":"The request is not valid.","fields":{"title":"String should have at least 1 character"}}}

The full contract is at http://localhost:3000/api/docs (Swagger UI, served by the backend through the same proxy).

5. Follow the request in the logs

docker compose logs backend --tail 5

Verification

• You can explain why the browser never needs the backend's address
• You saw 201, 404 and 422 with the same error shape
• You matched an x-request-id header to a backend log line

Exercises

1. In the browser, open the developer tools, Network tab, and ask a question in the assistant. Which URL is called? Which host?
2. Send {"title":"x","pinned":true} to POST /api/notes. Why does the API reject a field it does not know instead of ignoring it?
3. nginx limits /api/ask to a short burst per client (limit_req in nginx.conf). Send eight asks in a loop and find the 429.

Troubleshooting