ss-tools/.ai/standards/api_design.md

[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:

# [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:

@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]