1"""
2Production-ready REST API template using FastAPI.
3Includes pagination, filtering, error handling, and best practices.
4"""
5 
6from fastapi import FastAPI, HTTPException, Query, Path, Depends, status
7from fastapi.middleware.cors import CORSMiddleware
8from fastapi.middleware.trustedhost import TrustedHostMiddleware
9from fastapi.responses import JSONResponse
10from pydantic import BaseModel, Field, EmailStr, ConfigDict
11from typing import Optional, List, Any
12from datetime import datetime
13from enum import Enum
14 
15app = FastAPI(
16    title="API Template",
17    version="1.0.0",
18    docs_url="/api/docs"
19)
20 
21# Security Middleware
22# Trusted Host: Prevents HTTP Host Header attacks
23app.add_middleware(
24    TrustedHostMiddleware,
25    allowed_hosts=["*"] # TODO: Configure this in production, e.g. ["api.example.com"]
26)
27 
28# CORS: Configures Cross-Origin Resource Sharing
29app.add_middleware(
30    CORSMiddleware,
31    allow_origins=["*"], # TODO: Update this with specific origins in production
32    allow_credentials=False, # TODO: Set to True if you need cookies/auth headers, but restrict origins
33    allow_methods=["*"],
34    allow_headers=["*"],
35)
36 
37# Models
38class UserStatus(str, Enum):
39    ACTIVE = "active"
40    INACTIVE = "inactive"
41    SUSPENDED = "suspended"
42 
43class UserBase(BaseModel):
44    email: EmailStr
45    name: str = Field(..., min_length=1, max_length=100)
46    status: UserStatus = UserStatus.ACTIVE
47 
48class UserCreate(UserBase):
49    password: str = Field(..., min_length=8)
50 
51class UserUpdate(BaseModel):
52    email: Optional[EmailStr] = None
53    name: Optional[str] = Field(None, min_length=1, max_length=100)
54    status: Optional[UserStatus] = None
55 
56class User(UserBase):
57    id: str
58    created_at: datetime
59    updated_at: datetime
60 
61    model_config = ConfigDict(from_attributes=True)
62 
63# Pagination
64class PaginationParams(BaseModel):
65    page: int = Field(1, ge=1)
66    page_size: int = Field(20, ge=1, le=100)
67 
68class PaginatedResponse(BaseModel):
69    items: List[Any]
70    total: int
71    page: int
72    page_size: int
73    pages: int
74 
75# Error handling
76class ErrorDetail(BaseModel):
77    field: Optional[str] = None
78    message: str
79    code: str
80 
81class ErrorResponse(BaseModel):
82    error: str
83    message: str
84    details: Optional[List[ErrorDetail]] = None
85 
86@app.exception_handler(HTTPException)
87async def http_exception_handler(request, exc):
88    return JSONResponse(
89        status_code=exc.status_code,
90        content=ErrorResponse(
91            error=exc.__class__.__name__,
92            message=exc.detail if isinstance(exc.detail, str) else exc.detail.get("message", "Error"),
93            details=exc.detail.get("details") if isinstance(exc.detail, dict) else None
94        ).model_dump()
95    )
96 
97# Endpoints
98@app.get("/api/users", response_model=PaginatedResponse, tags=["Users"])
99async def list_users(
100    page: int = Query(1, ge=1),
101    page_size: int = Query(20, ge=1, le=100),
102    status: Optional[UserStatus] = Query(None),
103    search: Optional[str] = Query(None)
104):
105    """List users with pagination and filtering."""
106    # Mock implementation
107    total = 100
108    items = [
109        User(
110            id=str(i),
111            email=f"user{i}@example.com",
112            name=f"User {i}",
113            status=UserStatus.ACTIVE,
114            created_at=datetime.now(),
115            updated_at=datetime.now()
116        ).model_dump()
117        for i in range((page-1)*page_size, min(page*page_size, total))
118    ]
119 
120    return PaginatedResponse(
121        items=items,
122        total=total,
123        page=page,
124        page_size=page_size,
125        pages=(total + page_size - 1) // page_size
126    )
127 
128@app.post("/api/users", response_model=User, status_code=status.HTTP_201_CREATED, tags=["Users"])
129async def create_user(user: UserCreate):
130    """Create a new user."""
131    # Mock implementation
132    return User(
133        id="123",
134        email=user.email,
135        name=user.name,
136        status=user.status,
137        created_at=datetime.now(),
138        updated_at=datetime.now()
139    )
140 
141@app.get("/api/users/{user_id}", response_model=User, tags=["Users"])
142async def get_user(user_id: str = Path(..., description="User ID")):
143    """Get user by ID."""
144    # Mock: Check if exists
145    if user_id == "999":
146        raise HTTPException(
147            status_code=status.HTTP_404_NOT_FOUND,
148            detail={"message": "User not found", "details": {"id": user_id}}
149        )
150 
151    return User(
152        id=user_id,
153        email="[email protected]",
154        name="User Name",
155        status=UserStatus.ACTIVE,
156        created_at=datetime.now(),
157        updated_at=datetime.now()
158    )
159 
160@app.patch("/api/users/{user_id}", response_model=User, tags=["Users"])
161async def update_user(user_id: str, update: UserUpdate):
162    """Partially update user."""
163    # Validate user exists
164    existing = await get_user(user_id)
165 
166    # Apply updates
167    update_data = update.model_dump(exclude_unset=True)
168    for field, value in update_data.items():
169        setattr(existing, field, value)
170 
171    existing.updated_at = datetime.now()
172    return existing
173 
174@app.delete("/api/users/{user_id}", status_code=status.HTTP_204_NO_CONTENT, tags=["Users"])
175async def delete_user(user_id: str):
176    """Delete user."""
177    await get_user(user_id)  # Verify exists
178    return None
179 
180if __name__ == "__main__":
181    import uvicorn
182    uvicorn.run(app, host="0.0.0.0", port=8000)
183