api-design-patterns

API Design & Data Modeling Patterns

🔌 RESTFUL API DESIGN PATTERNS (From Backend Services)

Proven patterns for building consistent, scalable REST APIs with FastAPI.

📋 PYDANTIC MODEL PATTERNS:

1. Request/Response Model Structure

# ✅ Consistent model organization pattern
from pydantic import BaseModel, Field
from typing import List, Optional, Dict, Any, Union
from datetime import datetime

# Base models for common fields
class BaseResponse(BaseModel):
    """Base response with common fields."""
    status: str = Field(..., description="Operation status")
    message: str = Field(..., description="Human-readable message")
    timestamp: datetime = Field(default_factory=datetime.utcnow)

# Request models with validation
class ProcessRequest(BaseModel):
    """Request model with comprehensive validation."""
    data_path: str = Field(..., min_length=1, description="Path to data")
    options: Optional[Dict[str, Any]] = Field(default_factory=dict)
    
    class Config:
        # Enable validation on assignment
        validate_assignment = True
        # Example values for documentation
        schema_extra = {
            "example": {
                "data_path": "/path/to/data",
                "options": {"batch_size": 32, "format": "jpeg"}
            }
        }

# Response models with detailed typing
class ProcessResponse(BaseResponse):
    """Response model with job tracking."""
    job_id: str = Field(..., description="Unique job identifier")
    result: Optional[Dict[str, Any]] = Field(None, description="Processing result")

2. Collection Management Models

# ✅ Pattern from collections router
class CreateCollectionRequest(BaseModel):
    collection_name: str = Field(..., min_length=1, max_length=128)
    vector_size: int = Field(512, gt=0, description="Vector dimensionality")
    distance: str = Field('Cosine', description="Distance metric: Cosine|Dot|Euclid")

class CollectionInfo(BaseModel):
    """Comprehensive collection information."""
    name: str
    status: str
    points_count: int
    vectors_count: int
    config: Dict[str, Any]
    sample_points: List[Dict[str, Any]]
    is_active: bool
    created_at: Optional[datetime] = None
    updated_at: Optional[datetime] = None