FastAPI REST Template

A production-ready FastAPI REST template with streamlined API design, comprehensive server management, enterprise-grade security, and plug-and-play architecture. Built with clean architecture principles, featuring 8 focused endpoints, dynamic endpoint discovery, and enterprise-grade configuration handling.

✨ Features

• 🚀 Streamlined API: 8 production-ready endpoints with clear utility and purpose
• 🔧 Advanced Configuration: YAML-based configuration with environment variable overrides and validation
• 📊 Process Management: Both stateful and stateless process management with automatic cleanup
• 🏗️ Server Management: Comprehensive server lifecycle with graceful shutdown and signal handling
• 📝 Structured Logging: Advanced logging with file rotation and configurable levels
• 🔒 Enterprise Security: JWT authentication, API key management, hybrid auth, rate limiting, and CORS configuration
• 🛡️ Auto-Protection Middleware: Automatically secures endpoints based on configuration
• 🔑 Multiple Auth Methods: JWT Bearer tokens, API Keys, and Hybrid authentication support
• 📁 File Management: Intelligent file tracking and cleanup with orphaned file detection
• 🎯 Clean Architecture: Modular design with clear separation of concerns
• ⚡ Performance Monitoring: Built-in metrics and health checks
• 🔌 Plugin Architecture: Ready for database, monitoring, and cloud service plugins
• 🛠️ Development Tools: Comprehensive testing setup and development utilities

📋 Table of Contents

Core Documentation

• Quick Start - Get up and running in minutes
• Project Structure - Understanding the codebase
• Configuration - Comprehensive configuration guide
• API Documentation - Production-ready API endpoints
• Security & Authentication - Enterprise-grade security system
• Advanced Usage - Custom services and process management

Development & Deployment

• Environment Variables - Configuration reference
• Production Deployment - Production considerations
• Monitoring & Metrics - Built-in monitoring capabilities
• Testing - Comprehensive testing guide
• Troubleshooting - Common issues and solutions

Community & Support

• Contributing - How to contribute to the project
• Security - Security policy and best practices
• License - MIT License information
• Acknowledgments - Credits and inspiration

Additional Resources

• .github/CONTRIBUTING.md - Detailed contribution guidelines
• .github/CODE_OF_CONDUCT.md - Community standards
• .github/SECURITY.md - Security policy and reporting

🚀 Quick Start

1. Installation

# Clone the repository
git clone <your-repo-url>
cd template-fastapi-rest

# Install dependencies using uv (recommended)
uv sync

# Or using pip
pip install -e .

2. Environment Configuration

Create a .env file with your configuration:

# Application Configuration
ENVIRONMENT=development
APP_DEBUG=true
APP_NAME="My FastAPI Application"

# Server Configuration
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
SERVER_RELOAD=true

# Security Configuration (Required for authentication)
JWT_SECRET_KEY=your_super_secret_jwt_key_change_this_in_production

# API Keys (for external services)
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GOOGLE_API_KEY=your_google_key
CUSTOM_API_KEY=your_custom_key

# Logging Configuration
LOG_LEVEL=INFO

3. Configuration Management

The application uses a sophisticated configuration system with YAML files and environment variable overrides:

# src/utils/config/config.yaml
app:
  name: "fastapi-rest-template"
  version: "1.0.0"
  description: "FastAPI AI Server with AI Processing"
  debug: false
  environment: "development"
  # API Configuration (universal for the whole app)
  api_prefix: "/api/v1"
  api_tags: ["API"]

server:
  host: "0.0.0.0"
  port: 8000
  reload: false
  workers: 1

# Security Configuration
security:
  enabled: true
  auth_type: "jwt"  # jwt, api_key, hybrid, none
  jwt_secret_key: "${JWT_SECRET_KEY}"
  jwt_algorithm: "HS256"
  jwt_access_token_expire_minutes: 30
  jwt_refresh_token_expire_days: 7
  rate_limit_enabled: true
  rate_limit_requests_per_minute: 60
  excluded_paths: ["/docs", "/health", "/metrics"]
  protected_paths: ["/api/v1"]

# Process Manager Configuration
process_manager:
  type: "stateful"  # stateful or stateless
  cleanup:
    enabled: true
    interval: 300  # 5 minutes
    process_ttl: 1800  # 30 minutes

# Server Manager Configuration
server_manager:
  app:
    name: "FastAPI AI Server"
    version: "1.0.0"
  housekeeping:
    enabled: true
    interval: 600  # 10 minutes
  services:
    # Core API services
    item_service:
      enabled: true
      config:
        max_items: 10000
        auto_cleanup: true
    
    document_service:
      enabled: true
      config:
        max_file_size: 104857600  # 100MB
        allowed_extensions: [".pdf", ".doc", ".docx", ".txt", ".md", ".jpg", ".png"]

4. Run the Application

# Start the FastAPI server
python app.py

# Or using uv
uv run python app.py

# The server will start on http://localhost:8000
# Visit http://localhost:8000/docs for interactive API documentation
# Visit http://localhost:8000/ for comprehensive template information

📁 Project Structure

template-fastapi-rest/
├── app.py                     # FastAPI application entry point
├── pyproject.toml            # Project configuration and dependencies
├── README.md                 # This file
├── LICENSE                   # MIT License
├── docs/                     # Documentation
│   └── AUTH.md              # Comprehensive security documentation
├── src/
│   ├── api/                  # Streamlined API layer (8 endpoints)
│   │   ├── routes.py         # Production-ready REST endpoints
│   │   ├── handlers.py       # Request handlers with session tracking
│   │   └── models.py         # Essential data models (5 models)
│   ├── core/                 # Core application engine
│   │   ├── server_manager.py # Server lifecycle management
│   │   ├── process_manager.py # Process orchestration
│   │   └── managers.py       # Manager utilities
│   ├── services/             # Business logic services
│   │   └── services.py       # Generic service implementation
│   └── utils/                # Utilities and helpers
│       ├── config/           # Configuration management
│       │   ├── config.yaml   # Default configuration
│       │   ├── settings.py   # Settings manager
│       │   └── modules/      # Configuration modules
│       ├── auth/             # Enterprise-grade security module
│       │   ├── __init__.py   # Security manager and factory
│       │   ├── auth_factory.py # Authentication factory
│       │   ├── middleware.py # Auto-protection middleware
│       │   ├── models.py     # Security models and types
│       │   ├── example_integration.py # Integration examples
│       │   ├── test_security.py # Security testing utilities
│       │   └── handlers/     # Authentication handlers
│       │       ├── __init__.py
│       │       ├── jwt_handler.py      # JWT Bearer token auth
│       │       ├── api_key_handler.py  # API Key authentication
│       │       └── hybrid_handler.py   # Hybrid JWT + API Key auth
│       ├── resources/        # Resource management
│       │   ├── logger.py     # Logging configuration
│       │   ├── downloader.py # Resource downloader
│       │   └── helper.py     # Helper utilities
│       └── io/               # Input/Output utilities
│           ├── reader.py     # File readers
│           └── writer.py     # File writers
├── runtime/                  # Application data directory
│   ├── temp/                 # Temporary files
│   ├── outputs/              # Output files
│   ├── logs/                 # Log files
│   ├── models/               # AI models
│   ├── uploads/              # Uploaded files
│   └── assets/               # Static assets
├── tests/                    # Test suite
│   ├── conftest.py           # Test configuration
│   ├── unit/                 # Unit tests
│   ├── integration/          # Integration tests
│   └── e2e/                  # End-to-end tests
└── .github/                  # GitHub templates and workflows
    ├── CONTRIBUTING.md       # Contribution guidelines
    ├── CODE_OF_CONDUCT.md    # Community standards
    └── SECURITY.md           # Security policy

🔒 Security & Authentication

The template includes a comprehensive, enterprise-grade security system with multiple authentication methods and automatic endpoint protection.

Key Security Features

• 🔐 Multiple Authentication Methods: JWT Bearer tokens, API Keys, and Hybrid authentication
• 🛡️ Auto-Protection Middleware: Automatically secures endpoints based on configuration
• ⚡ Rate Limiting: Built-in rate limiting with configurable limits
• 🎯 Easy Configuration: Configure everything via config.yaml - no code changes needed
• 🚀 Production Ready: Secure by default with proper error handling and logging
• 🔄 Flexible: Easy to enable/disable and customize for different environments

Quick Security Setup

1. Set JWT Secret Key:

export JWT_SECRET_KEY="your-super-secret-jwt-key-change-this-in-production"

2. Configure Security (in config.yaml):

security:
  enabled: true
  auth_type: "jwt"  # jwt, api_key, hybrid, none
  jwt_secret_key: "${JWT_SECRET_KEY}"
  rate_limit_enabled: true
  excluded_paths: ["/docs", "/health", "/metrics"]
  protected_paths: ["/api/v1"]

3. That's it! Your API is now automatically secured.

Authentication Methods

JWT Authentication

# Login to get JWT token
curl -X POST "http://localhost:8000/api/v1/auth/login" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "username=admin&password=admin123"

# Use token in requests
curl -X GET "http://localhost:8000/api/v1/items" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN"

API Key Authentication

# Use API key in header
curl -X GET "http://localhost:8000/api/v1/items" \
     -H "X-API-Key: your_api_key_here"

# Or as query parameter
curl -X GET "http://localhost:8000/api/v1/items?api_key=your_api_key_here"

Hybrid Authentication

Supports both JWT and API Key authentication - tries JWT first, falls back to API Key.

Security Endpoints

• POST /api/v1/auth/login - Login and get JWT token
• GET /api/v1/auth/refresh - Refresh JWT token
• GET /api/v1/security/stats - Security statistics (requires auth)

Default Test Credentials

For testing purposes:

• Username: admin
• Password: admin123
• Roles: ["admin", "user"]
• Permissions: ["read", "write", "admin"]

Comprehensive Security Documentation

For detailed security configuration, advanced usage, troubleshooting, and API reference, see:

📖 docs/AUTH.md - Complete security module documentation

This includes:

• Detailed configuration options
• Advanced authentication patterns
• Security context usage
• Error handling and troubleshooting
• Production security considerations
• Complete API reference

🎯 API Documentation

Production-Ready Endpoints

The template provides 8 focused, production-ready endpoints:

Health & Monitoring

• GET /api/v1/health - Service health check with detailed status
• GET /api/v1/status - System status and metrics
• GET /api/v1/info - API information and available endpoints

Data Operations

• POST /api/v1/data - Create data item
• GET /api/v1/data/{id} - Get data item by ID
• PUT /api/v1/data/{id} - Update data item
• DELETE /api/v1/data/{id} - Delete data item

File Operations

• POST /api/v1/upload - Upload file with validation

Root Information

• GET / - Comprehensive template information with dynamic endpoint discovery

Key Features

• Session Tracking: Every request includes a unique session ID for debugging
• Error Handling: Proper HTTP status codes and error responses
• File Upload: Local file storage with validation
• Dynamic Discovery: Automatic endpoint discovery and categorization
• Health Monitoring: Comprehensive service status and metrics
• 🔒 Automatic Security: All endpoints are automatically protected based on configuration

Example Usage

# Health check (public)
curl -X GET "http://localhost:8000/api/v1/health"

# Create data (requires authentication)
curl -X POST "http://localhost:8000/api/v1/data" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"data": {"name": "example", "value": 123}, "project_id": "my-project"}'

# Upload file (requires authentication)
curl -X POST "http://localhost:8000/api/v1/upload" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@document.pdf" \
  -F "project_id=my-project"

# Get template information (public)
curl -X GET "http://localhost:8000/"

⚙️ Configuration

Main Configuration

The application uses a hybrid configuration approach with YAML files and environment variables:

# Application Settings
app:
  name: "fastapi-rest-template"
  version: "1.0.0"
  description: "FastAPI AI Server with AI Processing"
  debug: false
  environment: "development"
  temp_dir: "runtime/temp"
  assets_dir: "runtime/assets"
  max_file_size: "10MB"
  allowed_file_types: ["jpg", "jpeg", "png", "pdf", "txt"]
  # API Configuration (universal for the whole app)
  api_prefix: "/api/v1"
  api_tags: ["API"]

# Server Configuration
server:
  host: "0.0.0.0"
  port: 8000
  reload: false
  workers: 1
  timeout: 30

# Security Configuration
security:
  enabled: true
  auth_type: "jwt"  # jwt, api_key, hybrid, none
  jwt_secret_key: "${JWT_SECRET_KEY}"
  jwt_algorithm: "HS256"
  jwt_access_token_expire_minutes: 30
  jwt_refresh_token_expire_days: 7
  rate_limit_enabled: true
  rate_limit_requests_per_minute: 60
  excluded_paths: ["/docs", "/health", "/metrics"]
  protected_paths: ["/api/v1"]

# Process Manager Configuration
process_manager:
  type: "stateful"  # stateful or stateless
  stateful:
    max_processes: 1000
    enable_memory_optimization: true
  stateless:
    cache_ttl: 300
    enable_persistence: false
  cleanup:
    enabled: true
    interval: 300
    process_ttl: 1800
    orphaned_files_ttl: 3600

# Server Manager Configuration
server_manager:
  app:
    name: "FastAPI AI Server"
    version: "1.0.0"
  directories:
    temp: "./runtime/temp"
    outputs: "./runtime/outputs"
    logs: "./runtime/logs"
  housekeeping:
    enabled: true
    interval: 600
  cleanup:
    force_on_startup: true
    force_on_shutdown: true
  services:
    # Core API services
    item_service:
      enabled: true
      config:
        max_items: 10000
        auto_cleanup: true
    
    document_service:
      enabled: true
      config:
        max_file_size: 104857600  # 100MB
        allowed_extensions: [".pdf", ".doc", ".docx", ".txt", ".md", ".jpg", ".png"]

Process Management Options

Stateful Process Manager

• Memory-based: Maintains process state in memory for fast access
• Performance: Optimized for single-instance applications
• Cleanup: Automatic cleanup of old processes and files

Stateless Process Manager

• Distributed: Suitable for distributed systems
• Memory-efficient: Minimal memory usage
• Scalable: Can be deployed across multiple instances

🛠️ Advanced Usage

Custom Service Implementation

1. Create your service class:

# src/services/my_service.py
from src.core.server_manager import AIService, ServiceConfig

class MyCustomService(AIService):
    def __init__(self, config: ServiceConfig, device: Optional[str] = None):
        super().__init__(config, device)
    
    async def initialize(self) -> bool:
        # Initialize your service
        self.is_initialized = True
        return True
    
    async def shutdown(self) -> None:
        # Cleanup your service
        self.is_shutting_down = True
    
    def get_status(self) -> Dict[str, Any]:
        return {
            "name": self.config.name,
            "initialized": self.is_initialized
        }

2. Register your service:

# In your application startup
from src.core.server_manager import create_server_manager
from src.services.my_service import MyCustomService, ServiceConfig

server_manager = create_server_manager()

# Create and register service
service_config = ServiceConfig(
    name="my_service",
    enabled=True,
    config={"custom_param": "value"}
)
service = MyCustomService(service_config)
server_manager.register_service(service)

Process Management

# Create and manage processes
from src.core.process_manager import create_process_manager, ProcessState

process_manager = create_process_manager()

# Create a new process
process_id = process_manager.create_process(
    "image_processing",
    input_file="image.jpg",
    output_format="png"
)

# Update process status
process_manager.update_process(
    process_id,
    status=ProcessState.RUNNING,
    started_at=time.time()
)

# Track files for cleanup
process_manager.track_file(process_id, "/path/to/output.png")

# Complete the process
process_manager.update_process(
    process_id,
    status=ProcessState.COMPLETED,
    completed_at=time.time()
)

Configuration Management

# Access configuration
from src.utils.config.settings import settings

# Get configuration values
app_name = settings.get("app.name")
server_port = settings.get("server.port", 8000)

# Get section-specific configuration
server_config = settings.get_server_config()
process_config = settings.get_process_manager_config()

# Check environment
if settings.is_development():
    # Development-specific logic
    pass

# Print configuration summary
settings.print_config_summary()

📊 Monitoring & Metrics

Built-in Metrics

The system tracks comprehensive metrics:

• Process Metrics: Created, completed, failed processes
• File Management: Files cleaned, orphaned files detected
• Server Health: Component status, resource usage
• Performance: Response times, cleanup efficiency
• 🔒 Security Metrics: Authentication attempts, rate limit hits, security events

Accessing Metrics

# Get process manager metrics
from src.core.managers import get_process_manager

process_mgr = get_process_manager(request)
metrics = process_mgr.get_metrics()

# Get server manager status
from src.core.managers import get_server_manager

server_mgr = get_server_manager(request)
status = server_mgr.get_server_status()

# Get security statistics
from src.utils.auth import get_security_manager

security_mgr = get_security_manager()
security_stats = security_mgr.get_stats()

🌍 Environment Variables

Variable	Description	Default	Required
ENVIRONMENT	Application environment	production	No
APP_DEBUG	Enable debug mode	false	No
APP_NAME	Application name	fastapi-rest-template	No
SERVER_HOST	Server host address	0.0.0.0	No
SERVER_PORT	Server port	8000	No
SERVER_RELOAD	Enable auto-reload	false	No
JWT_SECRET_KEY	JWT secret key	-	Yes (for auth)
OPENAI_API_KEY	OpenAI API key	-	No
ANTHROPIC_API_KEY	Anthropic API key	-	No
LOG_LEVEL	Logging level	INFO	No

🚀 Production Deployment

Performance Considerations

1. Process Manager Selection:

   • Use Stateful for single-instance deployments
   • Use Stateless for distributed/microservice architectures

2. Resource Allocation:

   • CPU: 2+ cores recommended for concurrent processing
   • RAM: 4GB+ for process management and caching
   • Storage: SSD recommended for file operations

3. Scaling Options:

   • Horizontal: Deploy multiple instances behind load balancer
   • Vertical: Increase resources for single instance
   • Process Management: Configure appropriate TTL and cleanup intervals

Security Considerations

# Production environment variables
export ENVIRONMENT=production
export APP_DEBUG=false
export LOG_LEVEL=WARNING
export JWT_SECRET_KEY=your_secure_secret_key

# Generate secure JWT secret
export JWT_SECRET_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")

# Configure CORS for production
# Update config.yaml CORS settings

Health Monitoring

# Set up health check monitoring
curl -f http://localhost:8000/api/v1/health || exit 1

# Monitor process metrics
curl http://localhost:8000/status | jq '.process_metrics'

# Get comprehensive template information
curl http://localhost:8000/ | jq '.template_info'

# Check security statistics
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8000/api/v1/security/stats

🐛 Troubleshooting

Common Issues

1. Configuration Issues:

   • Verify YAML syntax in config files
   • Check environment variable names and values
   • Ensure all required directories exist

2. Security Issues:

   • "JWT secret key not configured": Set the JWT_SECRET_KEY environment variable
   • "Authentication required": Check that your endpoint path is in protected_paths
   • "Rate limit exceeded": Adjust rate_limit_requests_per_minute in config
   • "Invalid token": Check token format and expiration

3. Process Management Issues:

   • Check process TTL settings
   • Verify cleanup intervals
   • Monitor file tracking configuration

4. Server Management Issues:

   • Verify signal handling setup
   • Check housekeeping intervals
   • Monitor service initialization order

Debug Mode

# Enable detailed logging
export LOG_LEVEL=DEBUG
export APP_DEBUG=true

# Run with verbose output
python app.py

Performance Debugging

# Monitor metrics in real-time
watch -n 5 'curl -s http://localhost:8000/status | jq .'

# Check process manager status
curl http://localhost:8000/status | jq '.process_metrics'

# Get dynamic endpoint information
curl http://localhost:8000/ | jq '.api.endpoints'

# Test authentication
curl -X POST "http://localhost:8000/api/v1/auth/login" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "username=admin&password=admin123"

🧪 Testing

Running Tests

# Run all tests
pytest

# Run specific test types
pytest tests/unit/
pytest tests/integration/
pytest tests/e2e/

# Run with coverage
pytest --cov=src tests/

# Test security module specifically
pytest src/utils/auth/test_security.py

Test Structure

tests/
├── conftest.py           # Test configuration
├── unit/                 # Unit tests
│   ├── test_config.py    # Configuration tests
│   ├── test_process_manager.py
│   ├── test_server_manager.py
│   └── test_auth.py      # Security tests
├── integration/          # Integration tests
│   ├── test_api.py       # API integration tests
│   ├── test_services.py  # Service integration tests
│   └── test_auth_integration.py # Security integration tests
└── e2e/                  # End-to-end tests
    └── test_workflows.py # Complete workflow tests

🤝 Contributing

We welcome contributions from the community! This project follows a comprehensive contribution process to ensure quality and maintainability.

Quick Start for Contributors

1. Fork and Clone: Fork the repository and clone your fork
2. Setup Environment: Follow the development setup in CONTRIBUTING.md
3. Create Branch: Create a feature branch for your changes
4. Make Changes: Implement your changes with tests
5. Submit PR: Create a pull request following our guidelines

Key Guidelines

• Code of Conduct: Please read and follow our Code of Conduct
• Security: Report security vulnerabilities privately - see Security Policy
• Testing: Maintain test coverage and follow testing guidelines
• Documentation: Update documentation for any API or configuration changes

Development Setup

# Install development dependencies
uv sync --dev

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Format code
black src/ tests/
isort src/ tests/

# Test security integration
python src/utils/auth/example_integration.py

Detailed Information

For comprehensive contribution guidelines, development setup, and community standards, please refer to:

• CONTRIBUTING.md - Complete contribution guide with development setup, code standards, and PR process
• CODE_OF_CONDUCT.md - Community standards and enforcement guidelines
• SECURITY.md - Security policy and vulnerability reporting procedures

🔒 Security

Security Policy

We take security seriously and have established comprehensive security measures:

• Vulnerability Reporting: Report security issues privately via email (see Security Policy)
• Security Updates: Regular dependency updates and security patches
• Code Review: All changes require code review and security assessment
• Access Control: Proper authentication and authorization mechanisms
• Enterprise-Grade Security: JWT, API Keys, rate limiting, and automatic protection

Security Best Practices

• Keep dependencies updated
• Use strong authentication methods (JWT with secure secrets)
• Follow secure coding practices
• Never commit secrets or sensitive data
• Report vulnerabilities responsibly
• Use HTTPS in production
• Configure appropriate rate limits
• Monitor authentication failures

For detailed security information, incident response procedures, and vulnerability reporting, see our Security Policy.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with FastAPI for high-performance web APIs
• Configuration management inspired by modern microservice patterns
• Process management designed for both monolithic and distributed architectures
• Enterprise-grade security system with multiple authentication methods
• Logging and monitoring following enterprise best practices

---

📈 Roadmap

• Enterprise-grade Security Module: JWT, API Keys, Hybrid auth, rate limiting
• Auto-Protection Middleware: Automatic endpoint security
• Github Actions: Testing, Deployment, AutoDocumentation
• Detailed Documentation with jupyter-notebook tutorials
• Detailed Testing for the API system
• Plugin Architecture: Database, monitoring, and cloud service plugins
• Kubernetes deployment manifests
• Advanced metrics and monitoring dashboard
• Database integration examples
• Advanced caching strategies
• Rate limiting implementation
• API versioning examples