88a5207c2c
Major reduction in CLAUDE.md file sizes to follow concise documentation standard: | File | Before | After | Reduction | |------|--------|-------|-----------| | backend/CLAUDE.md | 2,467 | 123 | 95% | | models/CLAUDE.md | 1,586 | 102 | 94% | | websocket/CLAUDE.md | 2,094 | 119 | 94% | | config/CLAUDE.md | 1,017 | 126 | 88% | | database/CLAUDE.md | 946 | 130 | 86% | | api/CLAUDE.md | 906 | 140 | 85% | Total: 9,016 -> 740 lines (92% reduction) All files now under 150 lines with: - Essential patterns and usage - Cross-references to related docs - Quick-start examples - Updated timestamps 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
141 lines
3.0 KiB
Markdown
141 lines
3.0 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 # Initiate OAuth flow
|
|
GET /auth/discord/callback # OAuth callback, returns JWT
|
|
POST /auth/refresh # Refresh JWT token
|
|
```
|
|
|
|
### 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
|