How the Web Works

What Happens When You Type a URL

When you type https://bkk-sports-club.jongyang.xyz and press Enter, a chain of events happens:

1. DNS lookup: Your computer asks a DNS server "what IP address is bkk-sports-club.jongyang.xyz?" It gets back 195.201.126.8.
2. TCP connection: Your browser opens a connection to that IP on port 443 (HTTPS).
3. TLS handshake: Browser and server agree on encryption. The server proves its identity with a certificate (auto-managed by Caddy).
4. HTTP request: Browser sends a request: "GET / HTTP/1.1" with headers like Host: bkk-sports-club.jongyang.xyz.
5. Response: The server sends back HTML, CSS, JS. Browser renders it.

You type: https://bkk-sports-club.jongyang.xyz

  [Browser]
     │
     │ 1. DNS: "what IP is bkk-sports-club.jongyang.xyz?"
     │         Answer: 195.201.126.8
     │
     │ 2. TCP connect to 195.201.126.8:443
     │
     ▼
  [Caddy — reverse proxy]
     │  TLS terminates here. Caddy decrypts the request.
     │  Sees Host: bkk-sports-club.jongyang.xyz
     │  Routes to → nextjs container on port 3000
     │
     ▼
  [Next.js container :3000]
     │  Middleware rewrites: bkk-sports-club.jongyang.xyz/
     │  → internal route /shop/bkk-sports-club
     │  Fetches data from FastAPI
     │
     ▼
  [FastAPI container :8000]  →  [PostgreSQL :5432]
     Returns shop data as JSON

HTTP Methods — The Verbs

HTTP has "methods" that describe what you want to do with a resource. Think of them as verbs:

A key rule: GET requests must not change data. They are "safe" — you can call them 100 times and the result is the same. POST/PATCH/DELETE may change state.

HTTP Status Codes — The Answers

When a server responds, it includes a 3-digit status code. The first digit tells you the category:

• 2xx — Success
• 4xx — Your fault (bad request, not authorized, not found)
• 5xx — Server's fault

Codes you'll see in JongYang's FastAPI:

JSON — How Data Travels

HTTP requests and responses carry data. REST APIs use JSON (JavaScript Object Notation) — a text format that both humans and computers can read easily. It looks like this:

{
  "id": "705f95b6-010f-4038-adf1-427f1e0f5527",
  "shop_id": "fa2fd810-04a8-41f7-bcc1-dcb3889b9ac1",
  "resource_id": "02553923-fb55-443e-b87f-0f28b356b5b7",
  "service_id": null,
  "customer_name": "Test User",
  "customer_phone": "0812345678",
  "booking_date": "2026-06-25",
  "start_time": "07:00:00",
  "end_time": "08:00:00",
  "duration_min": 60,
  "total_price": "150.00",
  "status": "pending_payment",
  "promptpay_qr_url": "https://api.omise.co/charges/chrg_.../documents/docu_.../download",
  "expires_at": "2026-06-22T10:58:07.389599Z",
  "created_at": "2026-06-22T10:43:07.352663Z"
}

This is the JSON returned when a customer creates a booking. Notice:

• Keys are strings in double quotes
• Values can be strings, numbers, booleans, null, arrays, or nested objects
• null means "no value" (the service_id is null because this is an asset booking)
• Numbers don't need quotes; strings do
• The total_price is "150.00" as a string — because JSON numbers lose decimal precision, and money must be exact

What Is a REST API?

REST (Representational State Transfer) is a pattern for organizing web APIs. The key idea: treat everything as a resource, give it a URL, and use HTTP methods to operate on it.

JongYang's API is organized like this:

Resource: shops
  GET    /api/shops              → list all shops
  GET    /api/shops/{slug}       → get one shop by slug

Resource: availability
  GET    /api/availability/{resource_id}?date=2026-06-25&duration_min=60

Resource: bookings
  POST   /api/bookings           → create a booking
  GET    /api/bookings/{id}      → get a booking

Resource: admin bookings
  GET    /api/admin/bookings     → list shop's bookings (requires JWT)
  POST   /api/admin/bookings/{id}/confirm  → manually confirm

Notice /api/shops/{slug} — the {slug} is a path parameter. It's part of the URL. Compare with ?date=2026-06-25 — that's a query parameter, appended after ?. Path parameters identify which resource you want; query parameters filter or configure the response.

Why Separate Frontend and Backend?

JongYang has two separate applications:

• Frontend (Next.js) — runs in the browser (and partially on the Next.js server). Renders the UI. Knows nothing about databases.
• Backend (FastAPI) — runs on the server. Handles business logic, talks to the database, calls Omise, sends LINE messages.

They communicate via HTTP: the frontend makes API calls to https://api.jongyang.xyz/... and gets JSON back. This separation means:

• You can change the UI without touching the database code
• You can add a mobile app later that uses the same API
• The database is never directly exposed to the browser
• Different teams can work independently

Project Trace: Customer Books a Court

Let's walk through what happens when a customer fills out the booking form and clicks "Confirm & Pay":

BROWSER (React, running in customer's phone)
  │
  │  POST https://api.jongyang.xyz/api/bookings
  │  Body: {"resource_id":"...", "booking_date":"2026-06-25",
  │         "start_time":"07:00:00", "duration_min":60,
  │         "customer_name":"Test User", "customer_phone":"0812345678"}
  │
  ▼
CADDY (reverse proxy)
  │  Sees: Host: api.jongyang.xyz
  │  Routes to: fastapi container on port 8000
  │
  ▼
FASTAPI (create_booking function in routers/public/bookings.py)
  │  1. Validates the request body (Pydantic)
  │  2. Looks up the Resource in PostgreSQL
  │  3. Calculates end_time (07:00 + 60min = 08:00)
  │  4. Checks availability — is 07:00 actually free?
  │  5. Creates Booking row in PostgreSQL (status: "pending_payment")
  │  6. Calls Omise API → gets PromptPay QR URL
  │  7. Returns JSON with booking details + QR URL
  │
  ▼
BROWSER
  │  Receives 201 Created + booking JSON
  │  Shows the PromptPay QR code + 15-minute countdown timer
  │
  ▼  (customer scans QR with their banking app)
  │
OMISE API
  │  Receives payment → sends webhook to our server
  │
  ▼
FASTAPI (webhooks/omise.py)
     Updates booking.status = "confirmed"
     Sends LINE push notification to customer