API Request Flow¶

# backend/main.py:24-25 (FastAPI builtins)
from fastapi.middleware.cors import CORSMiddleware
from fastapi.middleware.gzip import GZipMiddleware

# backend/main.py:29-40
from backend.api.middleware import (
    BaggageMiddleware,
    BodySizeLimitMiddleware,
    ContentTypeValidationMiddleware,
    IdempotencyMiddleware,
    ObservabilityMiddleware,
    ProfilingMiddleware,
    RequestRecorderMiddleware,
    SecurityHeadersMiddleware,
    SetupGuardMiddleware,
)
from backend.api.middleware.request_id import RequestIDMiddleware

X-Request-ID: req-abc123def456

# Security headers added to all responses
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubDomains

# backend/main.py:35-71
from backend.api.routes import (
    admin,
    ai_audit,
    alertmanager,
    alerts,
    analytics,
    audit,
    calibration,
    cameras,
    debug,
    detections,
    dlq,
    entities,
    events,
    exports,
    feedback,
    health_ai_services,
    hierarchy,
    household,
    jobs,
    logs,
    media,
    metrics,
    notification,
    notification_preferences,
    prompt_management,
    queues,
    rum,
    services,
    settings_api,
    summaries,
    system,
    webhooks,
    websocket,
    zone_household,
    zones,
)

# Route handler with database dependency
@router.get("/events/{event_id}")
async def get_event(
    event_id: int,
    session: AsyncSession = Depends(get_session),
) -> EventResponse:
    result = await session.execute(
        select(Event).where(Event.id == event_id)
    )
    event = result.scalar_one_or_none()
    if not event:
        raise HTTPException(status_code=404, detail="Event not found")
    return EventResponse.from_orm(event)

# Route handler with Redis dependency
@router.get("/queue-stats")
async def get_queue_stats(
    redis: RedisClient = Depends(get_redis),
) -> QueueStatsResponse:
    detection_queue_len = await redis.llen(DETECTION_QUEUE)
    analysis_queue_len = await redis.llen(ANALYSIS_QUEUE)
    return QueueStatsResponse(
        detection_queue=detection_queue_len,
        analysis_queue=analysis_queue_len,
    )

Time 0ms:   Request received by Uvicorn
Time 1ms:   IdempotencyMiddleware — pass-through for GETs
Time 2ms:   BodySizeLimitMiddleware checks size
Time 3ms:   SecurityHeadersMiddleware prepares headers
Time 4ms:   CORS check (preflight OPTIONS stops here)
Time 5ms:   ObservabilityMiddleware starts timer (logs/metrics emitted on the way out)
Time 6ms:   RequestIDMiddleware assigns ID
Time 7ms:   ContentTypeValidationMiddleware validates
Time 8ms:   SetupGuardMiddleware check (503 if no users exist yet)
Time 9ms:   Route matching
Time 10ms:  Dependency resolution (get_session, per-route auth guards, etc.)
Time 12ms:  Handler execution starts
            ...
            Handler execution (variable)
            ...
Time N ms:  Handler returns response
Time N+1ms: RequestIDMiddleware echoes X-Request-ID / X-Correlation-ID
Time N+2ms: ObservabilityMiddleware adds X-Response-Time, logs completion,
            observes the duration histogram
Time N+3ms: Response sent (gzip-compressed if > 1 KB)

# Exception handler registration
register_exception_handlers(app)

{
  "detail": "Event not found",
  "request_id": "req-abc123def456",
  "timestamp": "2025-12-23T12:00:00Z"
}

{
  "detail": "Service temporarily unavailable",
  "service": "yolo26",
  "circuit_state": "open",
  "retry_after": 60
}

# Request body validation
class EventCreateRequest(BaseModel):
    camera_id: str = Field(..., min_length=1, max_length=50)
    risk_score: int = Field(..., ge=0, le=100)
    summary: str = Field(..., min_length=1, max_length=1000)

@router.post("/events")
async def create_event(
    request: EventCreateRequest,
) -> EventResponse:
    ...

@router.get("/events/{event_id}")
async def get_event(
    event_id: int = Path(..., ge=1, description="Event ID"),
) -> EventResponse:
    ...

@router.get("/events")
async def list_events(
    limit: int = Query(default=50, ge=1, le=100),
    offset: int = Query(default=0, ge=0),
    camera_id: str | None = Query(default=None),
    risk_level: str | None = Query(default=None),
) -> EventListResponse:
    ...

class EventResponse(BaseModel):
    id: int
    batch_id: str
    camera_id: str
    risk_score: int
    risk_level: str
    summary: str
    reasoning: str | None
    created_at: datetime
    acknowledged_at: datetime | None

    class Config:
        from_attributes = True

class PaginatedResponse(BaseModel, Generic[T]):
    items: list[T]
    total: int
    limit: int
    offset: int
    has_more: bool

# Response
{
    "items": [...],
    "total": 150,
    "limit": 50,
    "offset": 0,
    "has_more": true
}

1. Client sends:
   GET /api/events/42
   Headers:
     Accept: application/json

2. Middleware processing (outer to inner):
   - Idempotency: pass-through (GET is not a mutating method)
   - BodySizeLimit / SecurityHeaders / CORS: checked, pass
   - Observability: timer started
   - RequestID: req-abc123 assigned
   - SetupGuard: users exist, pass
   (No auth step: /api/events carries no auth guard — see Authentication Flow)

3. Route matching:
   - Matched: GET /api/events/{event_id}
   - Path params: event_id=42

4. Dependency injection:
   - AsyncSession created
   - Connection from pool

5. Handler execution:
   - SELECT * FROM events WHERE id = 42
   - Result: Event object

6. Response:
   HTTP/1.1 200 OK
   Content-Type: application/json
   X-Request-ID: req-abc123
   X-Content-Type-Options: nosniff

   {
     "id": 42,
     "batch_id": "batch-a1b2c3d4",
     "camera_id": "front_door",
     "risk_score": 75,
     "risk_level": "high",
     ...
   }

Trace: GET /api/events/42
  Span: http_request
    Span: db_query (SELECT events)
    Span: cache_check (Redis GET)