Skip to content

README.md

Latest commit

 

History

History
393 lines (298 loc) · 10.4 KB

README.md

File metadata and controls

393 lines (298 loc) · 10.4 KB

FastAPI Demo Server

A comprehensive FastAPI backend server demonstration showcasing various types of APIs, authentication, file uploads, and best practices.

Features

  • 🔐 JWT Authentication - Secure token-based authentication
  • 👥 User Management - Complete CRUD operations for users
  • 📦 Product Management - Product catalog with search and filtering
  • 📁 File Upload - Single and multiple file upload capabilities
  • 🔍 Search & Filtering - Advanced search and filtering options
  • 📚 API Documentation - Auto-generated Swagger/OpenAPI docs
  • 🛡️ Role-based Access Control - Admin and user roles
  • 🌐 CORS Support - Cross-origin resource sharing
  • ✅ Input Validation - Pydantic models for data validation
  • 🏗️ Clean Architecture - Well-organized folder structure

Project Structure

FastAPIServer/
├── app/
│   ├── api/              # API endpoints
│   │   ├── auth.py       # Authentication endpoints
│   │   ├── users.py      # User management endpoints
│   │   ├── products.py   # Product management endpoints
│   │   ├── files.py      # File upload endpoints
│   │   └── misc.py       # Miscellaneous endpoints
│   ├── core/             # Core functionality
│   │   ├── config.py     # Application configuration
│   │   └── security.py   # Security utilities
│   ├── models/           # Pydantic models
│   │   └── __init__.py   # Data models and schemas
│   └── services/         # Business logic
│       ├── user_service.py    # User business logic
│       └── product_service.py # Product business logic
├── tests/                # Test files
├── uploads/              # File upload directory
├── main.py              # Application entry point
├── pyproject.toml       # Project configuration
└── README.md           # This file

Installation

  1. Clone the repository:

    git clone <repository-url>
cd FastAPIServer

  2. Install dependencies:

    pip install -e .

    Or install with development dependencies:

    pip install -e ".[dev]"

Running the Server

Development Mode

python main.py

Production Mode

uvicorn main:app --host 0.0.0.0 --port 8000

The server will be available at:

API Endpoints

Authentication (/api/v1/auth)

Method Endpoint Description Auth Required
POST /token Login to get access token No
POST /register Register new user No
GET /me Get current user info Yes

Example - Login:

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

Example - Register:

curl -X POST "http://localhost:8000/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "email": "user@example.com",
    "password": "password123",
    "full_name": "New User"
  }'

User Management (/api/v1/users)

Method Endpoint Description Auth Required Admin Only
GET / List all users Yes No
GET /{user_id} Get user by ID Yes No
POST / Create new user Yes Yes
PUT /{user_id} Update user Yes Self/Admin
DELETE /{user_id} Delete user Yes Yes

Example - Get all users:

curl -X GET "http://localhost:8000/api/v1/users/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Product Management (/api/v1/products)

Method Endpoint Description Auth Required Admin Only
GET / List products No No
GET /search?q=term Search products No No
GET /{product_id} Get product by ID No No
POST / Create product Yes Yes
PUT /{product_id} Update product Yes Yes
DELETE /{product_id} Delete product Yes Yes

Query Parameters for GET /:

  • skip: Number of items to skip (pagination)
  • limit: Number of items to return (max 100)
  • category: Filter by category (electronics, clothing, books, home, sports)
  • in_stock: Filter by stock status (true/false)

Example - Get products:

curl -X GET "http://localhost:8000/api/v1/products/?category=electronics&in_stock=true"

Example - Search products:

curl -X GET "http://localhost:8000/api/v1/products/search?q=macbook"

File Upload (/api/v1/upload)

Method Endpoint Description Auth Required
POST /single Upload single file Yes
POST /multiple Upload multiple files Yes
GET /info Get upload constraints No

Supported File Types: jpg, jpeg, png, gif, pdf, txt, docx, xlsx Maximum File Size: 10MB Maximum Files per Request: 5 files

Example - Upload single file:

curl -X POST "http://localhost:8000/api/v1/upload/single" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@/path/to/your/file.pdf"

Miscellaneous (/api/v1/misc)

Method Endpoint Description
GET /health Health check
GET /ping Simple ping test
GET /time Get server time
GET /echo?message=hello Echo message
POST /echo Echo JSON data
GET /random-quote Get random quote
GET /weather?city=London Get weather (mock data)
GET /slow?delay=5 Slow endpoint (testing)
GET /error?status_code=404 Trigger error (testing)

Default Users

The application creates default users for testing:

Username Password Role Email
admin admin123 admin admin@example.com
john_doe user123 user john@example.com

Authentication Flow

  1. Register a new user or use default credentials
  2. Login to get an access token: 
    POST /api/v1/auth/token
{
  "username": "admin",
  "password": "admin123"
}
  3. Use the token in subsequent requests: 
    Authorization: Bearer YOUR_ACCESS_TOKEN

Data Models

User Model

{
  "id": 1,
  "username": "john_doe",
  "email": "john@example.com",
  "full_name": "John Doe",
  "role": "user",
  "is_active": true,
  "created_at": "2024-01-01T00:00:00",
  "updated_at": null
}

Product Model

{
  "id": 1,
  "name": "MacBook Pro",
  "description": "Apple MacBook Pro 16-inch with M2 chip",
  "price": 2499.99,
  "category": "electronics",
  "in_stock": true,
  "stock_quantity": 10,
  "created_at": "2024-01-01T00:00:00",
  "updated_at": null
}

Error Handling

The API uses standard HTTP status codes:

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 422 - Validation Error
  • 500 - Internal Server Error

Error responses follow this format:

{
  "detail": "Error message description"
}

Development

Running Tests

pytest

Code Formatting

black app/ tests/

Linting

flake8 app/ tests/

Configuration

The application can be configured using environment variables or a .env file:

# Application settings
APP_NAME=FastAPI Demo Server
DEBUG=true

# Security
SECRET_KEY=your-super-secret-key-change-this-in-production
ACCESS_TOKEN_EXPIRE_MINUTES=30

# CORS
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8080

Production Deployment

For production deployment:

  1. Set DEBUG=false
  2. Use a strong SECRET_KEY
  3. Configure proper CORS origins
  4. Use a production WSGI server like Gunicorn
  5. Set up a reverse proxy (nginx)
  6. Use a proper database instead of in-memory storage
  7. Implement proper logging and monitoring

Docker Deployment (Example)

FROM python:3.12-slim

WORKDIR /app
COPY . /app

RUN pip install -e .

EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

API Testing with curl

Complete workflow example:

# 1. Health check
curl http://localhost:8000/api/v1/misc/health

# 2. Login to get token
TOKEN=$(curl -X POST "http://localhost:8000/api/v1/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=admin123" | jq -r .access_token)

# 3. Get current user info
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/auth/me

# 4. List products
curl http://localhost:8000/api/v1/products/

# 5. Create a new product (admin only)
curl -X POST "http://localhost:8000/api/v1/products/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Product",
    "description": "A great product",
    "price": 99.99,
    "category": "electronics",
    "stock_quantity": 5
  }'

# 6. Upload a file
curl -X POST "http://localhost:8000/api/v1/upload/single" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@README.md"

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Run tests and linting
  6. Submit a pull request

License

This project is for demonstration purposes. Feel free to use it as a starting point for your FastAPI projects.

Support

For questions or issues, please create an issue in the repository or refer to the FastAPI documentation.