| 1 | # API Handlers DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own backend HTTP API handlers and WebSocket handler entry points. |
| 6 | - Keep route-level behavior, authentication, CSRF, input parsing, and response shapes explicit. |
| 7 | |
| 8 | ## Ownership |
| 9 | |
| 10 | - Files in this directory are discovered by the route registration layer in `helpers/api.py` and WebSocket registration code. |
| 11 | - `ws_*.py` files define WebSocket namespaces or handlers through `helpers.ws.WsHandler`. |
| 12 | - Plugin-provided API handlers belong inside plugin `api/` folders and follow the same base contracts. |
| 13 | |
| 14 | ## Local Contracts |
| 15 | |
| 16 | - HTTP handlers must derive from `helpers.api.ApiHandler`. |
| 17 | - Implement `async def process(self, input: dict, request: Request) -> dict | Response`. |
| 18 | - Override `get_methods()`, `requires_auth()`, `requires_csrf()`, `requires_api_key()`, or `requires_loopback()` only when the endpoint contract requires it. |
| 19 | - Keep CSRF and authentication protections intact for browser-facing state-changing endpoints. |
| 20 | - WebSocket handlers must derive from `helpers.ws.WsHandler` and validate event data before using it. |
| 21 | - Do not return secrets, raw environment values, private files, or unfiltered exception details to clients. |
| 22 | - This directory is a file-documented DOX profile: every direct `*.py` endpoint or WebSocket module must have a same-directory `*.py.dox.md` file named by appending `.dox.md` to the full Python filename. |
| 23 | - The `*.py.dox.md` file owns endpoint purpose, request/response concepts, auth/CSRF/API-key/loopback assumptions, side effects, important helper dependencies, and verification guidance. |
| 24 | - When a Python endpoint is added, removed, renamed, or behaviorally changed, update its matching `*.py.dox.md` in the same change. |
| 25 | - Do not leave stale file-level DOX after endpoint deletion or rename. |
| 26 | |
| 27 | ## Work Guidance |
| 28 | |
| 29 | - Use helpers for shared behavior instead of duplicating persistence, auth, file, project, plugin, or notification logic in endpoints. |
| 30 | - Keep request and response payloads stable; update frontend callers and tests together when payloads change. |
| 31 | - Prefer `Response` for files, redirects, status codes, and plain-text errors; return dictionaries for JSON success payloads. |
| 32 | - During the DOX pass, verify that every direct `*.py` file has a matching `*.py.dox.md` and that changed endpoint behavior is described there. |
| 33 | |
| 34 | ## Verification |
| 35 | |
| 36 | - Run targeted `pytest tests/test_*api*.py`, endpoint-specific tests, or WebSocket tests after changing handler behavior. |
| 37 | - For auth, CSRF, upload/download, tunnel, or file endpoints, run the nearest security regression tests. |
| 38 | - Check file-level documentation coverage with a script or shell loop that verifies each `api/*.py` has a matching `api/*.py.dox.md`. |
| 39 | |
| 40 | ## Child DOX Index |
| 41 | |
| 42 | No child DOX files. |