Kavosh/docs/api-contract-final.md

Chapter 11 — Final API Contract (post Ch08–12 additions)

Consolidated per Chapter 11's own instruction to update/extend the route table as new routes are introduced elsewhere, flagging additions explicitly.

Additions beyond the original Chapter 11 table

Method	Path	Blueprint	Purpose	Response	Added in
GET	/api/overview/browser-breakdown	overview	Human-only browser/OS breakdown	JSON	Ch08 (Method A)
GET	/	(root)	Redirect to /overview if authenticated, else /login	redirect	Ch12 follow-up
GET	/api/uploads	uploads	List uploaded files, paginated	JSON (Grid.js)	Ch12 follow-up
DELETE	/api/uploads	uploads	Bulk-delete uploaded files + derived data	JSON	Ch12 follow-up

/login, /logout, and /healthz were already listed in the original table (Ch02/Ch04) and are now actually implemented (Ch12) — no table change needed, just noting they're no longer placeholders. One narrowing: /logout is implemented as POST-only, not GET/POST, so a state-changing action isn't reachable via a plain GET (CSRF-safety; see app/blueprints/auth/routes.py).

Architecture note: rollup recompute is now delete-safe (Ch12 follow-up)

Deleting an uploaded file (app/services/file_deletion.py) removes its log_entries/bot_hits/suspicious_events rows explicitly (this project's SQLite connections don't have PRAGMA foreign_keys=ON, so the ondelete="CASCADE" in the migrations is documentation, not enforced behavior) and recomputes rollups for whatever dates the file touched. That recompute exposed a real bug in app/services/aggregator.py: three of its five writers only ever upserted-when-data-present and silently left stale rows behind when a day's data disappeared entirely — never reachable before deletion existed (rollups only ever grew). All five writers now use delete-then-insert consistently. See the module docstrings in aggregator.py and file_deletion.py for the full reasoning, including the deliberately-out-of-scope limitation around ip_registry/blocklist_suggestions not being recomputed on delete.

Architecture note: cron is now optional (Ch12 follow-up)

POST /uploads now triggers processing automatically in a background thread (app/services/background.py), and GET /overview opportunistically resumes any file left incomplete. flask process-logs and flask cleanup (app/cli.py) still exist and work identically to before for anyone who wants a cron-based fallback, but nothing in the app requires it anymore. See the module docstring in app/services/background.py for the explicit tradeoff this introduces relative to the original Chapter 02/03 "no persistent background workers, cron-triggered CLI only" stance.

Full current route table

Method	Path	Blueprint	Purpose	Response	Auth
GET	/overview	overview	Overview tab	full page / HTMX partial	required
GET	/api/overview/kpis	overview	KPI card values	JSON	required
GET	/api/overview/traffic-chart	overview	Traffic-over-time series	JSON	required
GET	/api/overview/status-codes	overview	Status-code breakdown	JSON	required
GET	/api/overview/top-urls	overview	Top URLs table	JSON (Grid.js)	required
GET	/api/overview/top-referrers	overview	Top referrers table	JSON (Grid.js)	required
GET	/api/overview/browser-breakdown	overview	Human browser/OS breakdown	JSON	required
GET	/seo	seo	SEO tab	full page / HTMX partial	required
GET	/api/seo/bot-summary	seo	Bot summary cards	JSON	required
GET	/api/seo/crawl-chart-data	seo	Crawl frequency series	JSON	required
GET	/api/seo/bot-status-codes	seo	Status codes served to bots	JSON	required
GET	/api/seo/crawled-vs-visited	seo	Bot vs. human URL comparison	JSON (Grid.js)	required
GET	/security	security	Security tab	full page / HTMX partial	required
GET	/api/security/events	security	Suspicious events table	JSON (Grid.js)	required
GET	/api/security/sensitive-paths	security	Sensitive-path summary	JSON	required
GET	/api/security/ip/<ip>	security	IP history drill-down	HTMX fragment	required
GET	/api/security/export-blocklist	security	Blocklist export	text/plain download	required
POST	/uploads	uploads	Upload a log file	HTMX fragment (queued state)	required
GET	/api/uploads/<id>/status	uploads	Poll parse status	JSON or HTMX fragment	required
GET	/api/uploads	uploads	List uploaded files	JSON (Grid.js)	required
DELETE	/api/uploads	uploads	Bulk-delete uploaded files	JSON	required
GET	/login	auth	Show login form	full page	public
POST	/login	auth	Authenticate	redirect	public
POST	/logout	auth	End session	redirect	required
GET	/healthz	(root)	Liveness check	JSON	public
GET	/	(root)	Auth-based redirect	redirect	public

Envelope compliance audit (Chapter 12)

Every /api/... JSON endpoint above was checked against Chapter 11's {"data": ..., "meta": {...}} / {"error": {"code", "message"}} convention. All conform. app/utils/envelope.py was added this chapter as a shared helper for new endpoints going forward (used by the unauthorized_handler in app/__init__.py) — existing endpoints already matched the shape by hand and weren't rewritten, to avoid churn on working code.

New this chapter: every /api/... path now returns a JSON 401 with {"error": {"code": "unauthorized", ...}} when unauthenticated, instead of Flask-Login's default redirect — consistent with the envelope even for auth failures. /api/security/ip/<ip> and /api/security/export- blocklist are the two exceptions where a successful response isn't JSON (HTMX fragment / text download, per the table above and Chapter 10) — their auth-failure response is still the JSON envelope for consistency.

Auth model (Chapter 12)

Every blueprint except auth and the root /healthz route requires a logged-in session (@bp.before_request + flask_login.login_required in each blueprint's __init__.py). This closes a gap that existed from Chapter 04 through Chapter 10: all dashboard and /api/... routes were reachable without authentication until Chapter 12 wired in Flask-Login, even though Chapter 01 specifies "one authenticated single-page shell."