Standardize API response envelope shapes across all endpoints
This commit standardizes how API responses are wrapped, solving issue #24. Problem: - Inconsistent response envelopes (jails vs items vs bans vs no wrapper) - Frontend required multiple field name variants - Integration bugs from branching logic - No clear pattern for different response types Solution: - Created response.py with base classes: PaginatedListResponse, CollectionResponse, CommandResponse - Standardized all list/collection responses to use 'items' field - Domain-specific field names for detail and aggregation responses - Updated all backends routers and mappers - Updated frontend types and hooks to match Changes: Backend: - backend/app/models/response.py (new): Base response models - backend/app/models/ban.py: Updated responses to inherit from bases - backend/app/models/jail.py: Updated JailListResponse, JailCommandResponse - backend/app/models/config.py: Updated collection responses - backend/app/services/jail_service.py: Updated return statements - backend/app/mappers/ban_mappers.py: Updated 'bans' to 'items' - backend/tests/test_mappers/test_ban_mappers.py: Updated tests Frontend: - frontend/src/types/jail.ts: Updated response interfaces - frontend/src/types/config.ts: Updated response interfaces - frontend/src/hooks/useActiveBans.ts: Updated selector - frontend/src/hooks/useJailList.ts: Updated selector - frontend/src/hooks/useJailConfigs.ts: Updated selector - frontend/src/hooks/useConfigActiveStatus.ts: Updated field access - frontend/src/hooks/useJailAdmin.ts: Updated field access Documentation: - Docs/Backend-Development.md: Added § 4.1 API Response Envelope Policy The policy defines: 1. Paginated lists use PaginatedListResponse (items, total, page, page_size) 2. Non-paginated collections use CollectionResponse (items, total) 3. Detail responses use entity-specific field names (jail, status, settings) 4. Command responses use CommandResponse (message, success, optional target) 5. Aggregations use domain-specific fields (jails, countries, buckets, bans) All responses now follow one of these patterns, reducing frontend complexity. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
@@ -6,6 +6,7 @@ Request, response, and domain models used by the jails router and service.
|
||||
from pydantic import BaseModel, ConfigDict, Field
|
||||
|
||||
from app.models.config import BantimeEscalation
|
||||
from app.models.response import CommandResponse, CollectionResponse
|
||||
|
||||
|
||||
class JailStatus(BaseModel):
|
||||
@@ -62,13 +63,13 @@ class JailSummary(BaseModel):
|
||||
status: JailStatus | None = None
|
||||
|
||||
|
||||
class JailListResponse(BaseModel):
|
||||
"""Response for ``GET /api/jails``."""
|
||||
class JailListResponse(CollectionResponse[JailSummary]):
|
||||
"""Response for ``GET /api/jails``.
|
||||
|
||||
model_config = ConfigDict(strict=True)
|
||||
Returns a non-paginated collection of jail summaries with their current status.
|
||||
"""
|
||||
|
||||
jails: list[JailSummary] = Field(default_factory=list)
|
||||
total: int = Field(..., ge=0)
|
||||
pass
|
||||
|
||||
|
||||
class JailDetailResponse(BaseModel):
|
||||
@@ -79,13 +80,13 @@ class JailDetailResponse(BaseModel):
|
||||
jail: Jail
|
||||
|
||||
|
||||
class JailCommandResponse(BaseModel):
|
||||
"""Generic response for jail control commands (start, stop, reload, idle)."""
|
||||
class JailCommandResponse(CommandResponse):
|
||||
"""Generic response for jail control commands (start, stop, reload, idle).
|
||||
|
||||
model_config = ConfigDict(strict=True)
|
||||
Extends the base CommandResponse with a jail field to identify the target.
|
||||
"""
|
||||
|
||||
message: str
|
||||
jail: str
|
||||
jail: str = Field(..., description="Target jail name, or '*' for operations on all jails.")
|
||||
|
||||
|
||||
class IgnoreIpRequest(BaseModel):
|
||||
|
||||
Reference in New Issue
Block a user