Merge pull request #487 from JnyJny/feature/fastapi-best-practices

FastAPI Best Practices Implementation and Logging Integration Fix

Author: JnyJny

docs/api/endpoints.md

@@ -1,8 +1,8 @@
 # Web API Overview
 
 The BusyLight HTTP API provides RESTful endpoints for controlling USB LED
-lights. The API returns JSON responses and supports the same functionality
-as the command-line interface.
+lights. Built with FastAPI, it features proper HTTP methods, domain-based 
+organization, API versioning, and comprehensive OpenAPI documentation.
 
 ## Quick Start
 
@@ -25,82 +25,107 @@ busyserve -D
 ### Basic Usage
 
 ```bash
-# Get server status
+# Get API information
 curl http://localhost:8000/
 
-# Turn light on (green)
-curl http://localhost:8000/light/0/on
+# Check system health
+curl http://localhost:8000/system/health
 
-# Turn light red
-curl "http://localhost:8000/light/0/on?color=red"
+# Turn light on (green) - REST endpoint
+curl -X POST http://localhost:8000/api/v1/lights/0/on \
+  -H "Content-Type: application/json" \
+  -d '{"color": "green", "dim": 1.0, "led": 0}'
 
-# Blink light blue 3 times
-curl "http://localhost:8000/light/0/blink?color=blue&count=3"
+# Turn light red - backwards compatible
+curl "http://localhost:8000/light/0/on?color=red"
 
-# Turn light off
-curl http://localhost:8000/light/0/off
+# Start rainbow effect
+curl -X POST http://localhost:8000/api/v1/effects/rainbow \
+  -H "Content-Type: application/json" \
+  -d '{"dim": 0.8, "speed": "fast"}'
 ```
 
 ## API Features
 
-- **RESTful design** with consistent JSON responses
+- **Domain-based organization** - lights, effects, system endpoints
+- **API versioning** - v1 endpoints with backwards compatibility
+- **Proper HTTP methods** - POST for actions, GET for queries  
+- **JSON request/response** with Pydantic validation
 - **Device targeting** by index or all devices
 - **LED targeting** for multi-LED devices
-- **Color specification** via query parameters
-- **Effect control** with customizable parameters
 - **Authentication** via HTTP Basic Auth (optional)
 - **CORS support** for browser-based applications
 - **Interactive documentation** at `/docs` and `/redoc`
+- **OpenAPI 3.0** specification for code generation
+
+## API Endpoints
+
+The API provides multiple access patterns:
 
-## Base URL
+### Versioned API (Recommended)
+```
+http://localhost:8000/api/v1/
+```
 
+### Backwards Compatible
 ```
-http://localhost:8000
+http://localhost:8000/
 ```
 
 Default host is `localhost` and port is `8000`. Configure with command-line
 options:
 
 ```bash
-busyserve --host 0.0.0.0 --port 8080
+busyserve --host 0.0.0.0 --port 8080 --debug  # Enable debug logging
 ```
 
 ## Response Format
 
 All endpoints return JSON responses with consistent structure:
 
-### Success Response
+### Light Operation Response
 
 ```json
 {
-  "action": "on",
-  "light_id": 0,
-  "color": "red", 
-  "rgb": [255, 0, 0],
-  "led": 0
+  "success": true,
+  "action": "turned on",
+  "lights_affected": 1,
+  "details": [
+    {
+      "light_id": 0,
+      "action": "turned on", 
+      "color": "red",
+      "rgb": [255, 0, 0],
+      "dim": 1.0,
+      "led": 0
+    }
+  ]
 }
 ```
 
 ### Error Response
 
 ```json
 {
-  "message": "Light index 5 not found"
+  "detail": "Light index 5 not found"
 }
 ```
 
 ## Content Types
 
-- **Request**: Query parameters or JSON body
-- **Response**: `application/json`
+- **V1 Endpoints**: JSON request/response (`application/json`)
+- **Compatibility Endpoints**: Query parameters with JSON response
+- **All Responses**: `application/json`
 
 ## Status Codes
 
 | Code | Description |
 |------|-------------|
 | 200 | Success |
+| 401 | Authentication required |
 | 404 | Device not found |
-| 422 | Invalid parameter |
+| 422 | Validation error |
+| 503 | No lights available |
 | 500 | Server error |
 
 ## Authentication
@@ -121,8 +146,13 @@ busyserve
 ### Usage
 
 ```bash
-# Authenticated request
-curl -u admin:secret http://localhost:8000/light/0/on
+# V1 authenticated request
+curl -u admin:secret -X POST http://localhost:8000/api/v1/lights/0/on \
+  -H "Content-Type: application/json" \
+  -d '{"color": "red"}'
+
+# Compatibility authenticated request  
+curl -u admin:secret http://localhost:8000/light/0/on?color=red
 ```
 
 !!! warning "Security Warning"
@@ -165,20 +195,70 @@ These interfaces allow testing endpoints directly from the browser.
 The API does not impose rate limiting, but devices may have physical
 limitations on how quickly they can change colors or effects.
 
-## Health Check
+## System Endpoints
 
 ```bash
-# Check server status
+# API information
 curl http://localhost:8000/
 
-# Response
-[
-  {"path": "/"},
-  {"path": "/lights"},
-  {"path": "/light/{light_id}"}
-]
+# System health check
+curl http://localhost:8000/system/health
+
+# System information
+curl http://localhost:8000/system/info
 ```
 
+### Health Response
+```json
+{
+  "status": "healthy",
+  "lights_available": 2,
+  "timestamp": "2023-01-01T12:00:00Z"
+}
+```
+
+## Backwards Compatibility
+
+The API maintains full backwards compatibility with existing integrations:
+
+- **Original endpoints** work unchanged (GET requests with query parameters)
+- **Original response format** preserved for compatibility endpoints
+- **Gradual migration** - use v1 endpoints for new features, keep existing code working
+- **Deprecation warnings** in OpenAPI docs for legacy endpoints
+
+### Migration Path
+
+1. **Keep existing code working** - no immediate changes needed
+2. **New features** - use `/api/v1/` endpoints with JSON payloads
+3. **Gradual adoption** - migrate endpoints one at a time
+4. **Full migration** - eventually adopt v1 endpoints for all operations
+
+## Logging
+
+The API uses integrated logging that properly displays both FastAPI and uvicorn events:
+
+```bash
+# Normal logging
+busyserve
+
+# Debug logging with detailed output
+busyserve --debug
+```
+
+**Features:**
+- **Integrated logging** - All API, uvicorn, and application events appear in a unified log
+- **Color-coded output** - Different log levels are visually distinct  
+- **Request tracing** - HTTP requests and responses are logged when debug is enabled
+- **Structured format** - Timestamps, levels, module names, and line numbers included
+
+**Log Levels:**
+- **INFO**: Server startup, configuration, API operations
+- **DEBUG**: Detailed request/response data, internal operations  
+- **WARNING**: Configuration issues, recoverable errors
+- **ERROR**: Request failures, server errors
+
+**Previous Issue Resolved:** Earlier versions had logging compatibility issues between loguru and uvicorn - this has been fixed with integrated logging handlers.
+
 ## Error Handling
 
 The API provides detailed error messages for troubleshooting: