Lesson 8 — Beginner

Capstone: Ship a No-AI REST Service

Ab tak sab alag-alag the — ab sab ek saath. Is capstone mein tum ek chhoti service banayenge bina kisi AI feature ke: Python + FastAPI + PostgreSQL + tests + git workflow + Docker + public deploy. Neeche clear spec, build plan aur ship checklist di hai — ise follow karke apna pehla deployable service le aao.

Capstone kya hai aur kyun

Capstone ka asli maksad code nahi — maksad hai process: spec likhna, plan banana, agent se collaborate karke chhote diffs mein build karna, har diff verify karna, aur end-to-end ship karna. Ek din mein ho jaane wala kaam hai — lekin steps mat chhodna.

Scope chhota rakho, spec pehle likho

# Service: Bookings API (no-AI)

## Resources
rooms    : {id, name, capacity}
bookings : {id, room_id, start, end, guest}

## Endpoints
GET    /health        -> 200 {"status": "ok"}
GET    /rooms         -> 200 list
POST   /rooms         -> 201 | 422
GET    /bookings      -> 200 list (?room_id= filter)
POST   /bookings      -> 201 | 409 clash (overlapping time)
GET    /bookings/{id} -> 200 | 404
DELETE /bookings/{id} -> 204 | 404

## Rules
- Har input Pydantic se validated, ISO times, past booking = 422
- Errors: {"error": "...", "code": "..."} — har jagah same shape
- Write routes par X-API-Key header

• Do resources, ~7 endpoints — itna kaafi hai. Zyada resources = debug aur deploy mein time jaayega, seekhna kam. Scope creep ka dar sabse zyada yahin hota hai.
• Har endpoint ka status code pehle likho — 409 clash rule jaisi domain logic spec mein hi honi chahiye, baad mein yaad nahi aayegi.
• Acceptance checklist spec ka hissa hai: jiski tick se feature done. Ye hi aage test cases banenge.

Repo layout aur build order

repo/
├── app/
│   ├── main.py          # app + lifespan
│   ├── config.py        # env vars (Pydantic Settings)
│   ├── db.py            # connection + pool
│   ├── routes/          # rooms.py, bookings.py
│   └── schemas.py       # Pydantic in/out models
├── tests/               # test_rooms.py, test_bookings.py
├── .env.example         # keys ka sample (commit hota hai)
├── .gitignore
├── Dockerfile
├── pyproject.toml
└── README.md

# Order — har step par tests green, har step ek commit
1. uv init + FastAPI skeleton + /health
2. Pydantic schemas + rooms CRUD (in-memory)
3. PostgreSQL swap + credentials env se
4. bookings + 409 clash rule + filters
5. README + Dockerfile
6. Deploy + smoke test -> tag v1.0

• Har step ek commit — review aur revert dono aasaan. Ek commit mein 400 lines = kaunsa change kyun tha pata nahi chalta.
• Agent ka use: step ka task likho (context + files + check), diff padho, test chalao, accept. Sab kuch ek baar mein mat karwao.
• Pehle API shape set karo, phir DB swap karo — dono ek saath karoge toh bug kahan hai pata nahi chalega.
• README har step ke baad thoda update — last day pe poora likhne ki zarurat nahi padegi.

Ship checklist — local se public tak

# Ship se pehle (local — chaaro green)
uv run ruff check . && uv run mypy app && uv run pytest -q
docker build -t bookings-api:1.0 .
docker run --rm -p 8000:8000 --env-file .env bookings-api:1.0

# Ship (platform: image + env vars) ke baad — smoke test
curl -sS https://<public-url>/health
curl -sS https://<public-url>/rooms
curl -sS -X POST https://<public-url>/rooms -H "Content-Type: application/json" -d @room.json

# Har response ka STATUS CODE dekho (201/409/422) — sirf body nahi
git tag v1.0 && git push --tags

• Lint + types + tests + local container — chaaro green se pehle deploy mat karo.
• Public URL par sirf health se mat maano — ek real POST karke dekho: DB config wahi hoti hai jo local mein alag hoti hai.
• Failure aaye toh order: platform logs -> container logs -> env vars -> smoke phir se. Wahi debugging jo Containers lesson mein sikhi.
• Demo ke liye: README ka 5-line intro, endpoint table aur public URL — interviewer ko minute mein yahi chahiye.

Exercise

Common mistakes

• Scope badha lena: Auth system, websockets, microservices — sab add karne ki koshish mein ship hi nahi hota. Fix: do resources, ~7 endpoints. Baaki "baad mein" list mein.
• Deploy ko pehla step banana: Lint/test bina deploy kiya toh cloud par debug karna mehnga. Fix: local par hi wahi image chala kar smoke test, tabhi push.
• README aur tests last day ke liye chhod dena: Aakhri din sab ek saath likhna = galtiyan chhupti hain. Fix: har step ke saath chhota update — ending mein sirf polish bachi hai.

Naksha   : spec -> 2 resources, 7 endpoints, status codes fix
Material : uv + FastAPI + PostgreSQL + pytest
Building : har kamra ek commit, har step par test (verification loop)
Shift    : docker build -> platform -> public URL -> curl smoke
Pehla din: git tag v1.0 — ship ho gaya!