9c90893b5d
Updated CLAUDE.md files with: - Current test counts and status - Session injection pattern documentation - New module references and architecture notes - Updated Phase status (3E-Final complete) - Enhanced troubleshooting guides Files updated: - Root CLAUDE.md: Project overview and phase status - backend/CLAUDE.md: Backend overview with test counts - backend/README.md: Quick start and development guide - backend/app/api/CLAUDE.md: API routes documentation - backend/app/database/CLAUDE.md: Session injection docs - backend/app/utils/CLAUDE.md: Utilities documentation - backend/tests/CLAUDE.md: Testing patterns and policy - frontend-sba/CLAUDE.md: Frontend overview - frontend-sba/store/CLAUDE.md: Store patterns 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
146 lines
3.4 KiB
Markdown
146 lines
3.4 KiB
Markdown
# API Module - REST Endpoints
|
|
|
|
## Purpose
|
|
|
|
REST API endpoints using FastAPI. Handles authentication, health checks, and supplementary game operations not suited for WebSocket (e.g., initial page loads, file uploads).
|
|
|
|
## Structure
|
|
|
|
```
|
|
app/api/
|
|
├── __init__.py # Package marker
|
|
├── dependencies.py # FastAPI dependencies (auth, db session)
|
|
└── routes/
|
|
├── health.py # Health check endpoints
|
|
├── auth.py # Discord OAuth flow
|
|
└── games.py # Game CRUD operations
|
|
```
|
|
|
|
## Routes
|
|
|
|
### Health (`/health`)
|
|
```python
|
|
GET /health # Basic health check
|
|
GET /health/ready # Ready check with DB connectivity
|
|
```
|
|
|
|
### Auth (`/auth`)
|
|
```python
|
|
GET /auth/discord/login # Initiate OAuth flow (redirects to Discord)
|
|
GET /auth/discord/callback/server # OAuth callback, sets HttpOnly cookies, redirects to frontend
|
|
GET /auth/me # Get current user from cookie (SSR-compatible)
|
|
POST /auth/refresh # Refresh access token using refresh cookie
|
|
POST /auth/logout # Clear auth cookies
|
|
```
|
|
|
|
**Cookie-Based Auth**: Uses HttpOnly cookies with `path="/"` for SSR compatibility.
|
|
See `COOKIE_AUTH_IMPLEMENTATION.md` for complete flow documentation.
|
|
|
|
### Games (`/games`)
|
|
```python
|
|
POST /games # Create new game
|
|
GET /games # List user's games
|
|
GET /games/{id} # Get game details
|
|
GET /games/{id}/lineup # Get game lineup
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
### Authentication
|
|
```python
|
|
from app.api.dependencies import get_current_user
|
|
|
|
@router.get("/games")
|
|
async def list_games(user: User = Depends(get_current_user)):
|
|
# user is authenticated
|
|
```
|
|
|
|
### Database Session
|
|
```python
|
|
from app.api.dependencies import get_db
|
|
|
|
@router.post("/games")
|
|
async def create_game(db: AsyncSession = Depends(get_db)):
|
|
# Use db for operations
|
|
```
|
|
|
|
## FastAPI Patterns
|
|
|
|
### Request Validation
|
|
```python
|
|
from pydantic import BaseModel
|
|
|
|
class CreateGameRequest(BaseModel):
|
|
league_id: str
|
|
home_team_id: int
|
|
away_team_id: int
|
|
|
|
@router.post("/games")
|
|
async def create_game(request: CreateGameRequest):
|
|
# request is validated
|
|
```
|
|
|
|
### Response Model
|
|
```python
|
|
class GameResponse(BaseModel):
|
|
id: UUID
|
|
status: str
|
|
home_score: int
|
|
away_score: int
|
|
|
|
@router.get("/games/{id}", response_model=GameResponse)
|
|
async def get_game(id: UUID):
|
|
...
|
|
```
|
|
|
|
### Error Handling
|
|
```python
|
|
from fastapi import HTTPException
|
|
|
|
if not game:
|
|
raise HTTPException(status_code=404, detail="Game not found")
|
|
```
|
|
|
|
## Common Tasks
|
|
|
|
### Add New Endpoint
|
|
1. Create route in `app/api/routes/`
|
|
2. Define Pydantic request/response models
|
|
3. Add dependencies (auth, db)
|
|
4. Register router in `app/main.py`
|
|
|
|
### Protected Route
|
|
```python
|
|
@router.get("/protected")
|
|
async def protected_route(
|
|
user: User = Depends(get_current_user)
|
|
):
|
|
return {"user_id": user.id}
|
|
```
|
|
|
|
## Registration
|
|
|
|
Routes are registered in `app/main.py`:
|
|
```python
|
|
from app.api.routes import health, auth, games
|
|
|
|
app.include_router(health.router, prefix="/health")
|
|
app.include_router(auth.router, prefix="/auth")
|
|
app.include_router(games.router, prefix="/games")
|
|
```
|
|
|
|
## API Docs
|
|
|
|
FastAPI auto-generates documentation:
|
|
- Swagger UI: `http://localhost:8000/docs`
|
|
- ReDoc: `http://localhost:8000/redoc`
|
|
|
|
## References
|
|
|
|
- **WebSocket**: Main game communication via `../websocket/CLAUDE.md`
|
|
- **Auth Utilities**: See `../utils/auth.py`
|
|
|
|
---
|
|
|
|
**Updated**: 2025-01-19
|