48 lines
1.8 KiB
Markdown
48 lines
1.8 KiB
Markdown
# [DEF:Std:API_FastAPI:Standard]
|
|
# @TIER: CRITICAL
|
|
# @PURPOSE: Unification of all FastAPI endpoints following GRACE-Poly.
|
|
# @LAYER: UI (API)
|
|
# @INVARIANT: All non-trivial route logic must be wrapped in `belief_scope`.
|
|
# @INVARIANT: Every module and function MUST have `[DEF:]` anchors and metadata.
|
|
|
|
## 1. ROUTE MODULE DEFINITION
|
|
Every API route file must start with a module definition header:
|
|
```python
|
|
# [DEF:ModuleName:Module]
|
|
# @TIER: [CRITICAL | STANDARD | TRIVIAL]
|
|
# @SEMANTICS: list, of, keywords
|
|
# @PURPOSE: High-level purpose of the module.
|
|
# @LAYER: UI (API)
|
|
# @RELATION: DEPENDS_ON -> [OtherModule]
|
|
```
|
|
|
|
## 2. FUNCTION DEFINITION & CONTRACT
|
|
Every endpoint handler must be decorated with `[DEF:]` and explicit metadata before the implementation:
|
|
```python
|
|
@router.post("/endpoint", response_model=ModelOut)
|
|
# [DEF:function_name:Function]
|
|
# @PURPOSE: What it does (brief, high-entropy).
|
|
# @PARAM: param_name (Type) - Description.
|
|
# @PRE: Conditions before execution (e.g., auth, existence).
|
|
# @POST: Expected state after execution.
|
|
# @RETURN: What it returns.
|
|
async def function_name(...):
|
|
with belief_scope("function_name"):
|
|
# Implementation
|
|
pass
|
|
# [/DEF:function_name:Function]
|
|
```
|
|
|
|
## 3. DEPENDENCY INJECTION & CORE SERVICES
|
|
* **Auth:** `Depends(get_current_user)` for authentication.
|
|
* **Perms:** `Depends(has_permission("resource", "ACTION"))` for RBAC.
|
|
* **Config:** Use `Depends(get_config_manager)` for settings. Hardcoding is FORBIDDEN.
|
|
* **Tasks:** Long-running operations must be executed via `TaskManager`. API routes should return Task ID and be non-blocking.
|
|
|
|
## 4. ERROR HANDLING
|
|
* Raise `HTTPException` from the router layer.
|
|
* Use `try-except` blocks within `belief_scope` to ensure proper error logging and classification.
|
|
* Do not leak internal implementation details in error responses.
|
|
|
|
# [/DEF:Std:API_FastAPI]
|