ariffazil/FORGE-fastapi-api-builder

⚒️ FastAPI API Builder — Organ Bridge Middleware

DITEMPA BUKAN DIBERI — Forged, Not Given.

Purpose

Build and maintain FastAPI/Node API endpoints for /api/observatory/v1/* and organ bridge surfaces: middleware stack, CORS, error handling, health probes, MCP proxy endpoints.

When to Use

• Creating new API endpoints in arifOS, GEOX, WEALTH, WELL FastAPI servers
• Adding middleware — auth, CORS, request logging, rate limiting
• Error handling patterns — structured error responses, exception handlers
• MCP-to-HTTP bridge endpoints for observatory consumption

When NOT to Use

• Frontend routes — use nextjs-mastery or react-spa-discipline
• Database schema design — use postgres-schema-design
• Deployment/Docker — use cicd-docker-deploy

Constitutional Floor Alignment

| Floor | Application | |-------|-------------| | F1 AMANAH | Version all breaking API changes (/v1/, /v2/); never mutate in place | | F2 TRUTH | Response schemas must match documented contracts; no undocumented fields | | F4 CLARITY | One endpoint = one responsibility; no mega-endpoints | | F11 AUDIT | Every request logged with actor, intent, timestamp | | F12 INJECTION | All inputs sanitized; never trust request body without validation |

Commands & Patterns

# FastAPI organ endpoint pattern
from fastapi import APIRouter, HTTPException
from pydantic import BaseModel

router = APIRouter(prefix="/api/observatory/v1")

class HealthResponse(BaseModel):
    status: str
    version: str
    uptime: float

@router.get("/health", response_model=HealthResponse)
async def health():
    return {"status": "ok", "version": "1.0.0", "uptime": time.monotonic()}

# CORS middleware
app.add_middleware(CORSMiddleware, allow_origins=["https://arifos.arif-fazil.com"])

# Structured error handler
@app.exception_handler(AppError)
async def app_error_handler(request, exc):
    return JSONResponse(status_code=exc.code, content={"error": exc.message, "trace": exc.trace_id})

Refusal Surface

• ❌ Endpoints that mutate without lease/session auth
• ❌ Returning raw database models as response (always use Pydantic schema)
• ❌ Skipping input validation on POST/PUT/PATCH endpoints
• ❌ Hardcoded organ ports in API routes — use env config
• ❌ Sync endpoints for I/O-bound operations (must be async)