📘 FastAPI: Modern APIs

🎯 Introduction

Welcome to the exciting world of FastAPI! 🎉 In this guide, we’ll explore how to build lightning-fast ⚡ modern APIs with Python.

Imagine building APIs as fast as writing a simple Python function - that’s the magic of FastAPI! Whether you’re creating microservices 🏗️, RESTful APIs 🌐, or real-time applications 🚀, FastAPI makes it incredibly easy and fun.

By the end of this tutorial, you’ll be building professional-grade APIs with automatic documentation, validation, and blazing performance! Let’s dive in! 🏊‍♂️

📚 Understanding FastAPI

🤔 What is FastAPI?

FastAPI is like having a super-smart assistant 🤖 that helps you build web APIs. Think of it as a framework that takes your Python functions and transforms them into powerful web endpoints that can talk to any application!

In Python terms, FastAPI is a modern web framework that uses Python type hints to:

✨ Automatically validate request/response data
🚀 Generate interactive API documentation
🛡️ Provide built-in security features
⚡ Deliver incredible performance

💡 Why Use FastAPI?

Here’s why developers love FastAPI:

Type-First Design 🔒: Uses Python type hints for automatic validation
Automatic Documentation 💻: Interactive docs generated from your code
Modern Python 📖: Built on Python 3.8+ features
Incredible Performance 🔧: One of the fastest Python frameworks

Real-world example: Imagine building an e-commerce API 🛒. With FastAPI, you get automatic validation of product data, interactive documentation for your frontend team, and performance that handles thousands of requests per second!

🔧 Basic Syntax and Usage

📝 Your First FastAPI App

Let’s start with a friendly example:

# 👋 Hello, FastAPI!
from fastapi import FastAPI

# 🎨 Create your FastAPI app
app = FastAPI()

# 🎯 Define your first endpoint
@app.get("/")
def read_root():
    return {"message": "Welcome to FastAPI! 🎉"}

# 👤 Create a user endpoint
@app.get("/users/{user_id}")
def read_user(user_id: int):
    return {"user_id": user_id, "name": f"User {user_id} 🧑‍💻"}

💡 Explanation: Notice how simple it is! Just decorate your Python functions with @app.get() and FastAPI turns them into web endpoints. The type hint user_id: int automatically validates that the parameter is an integer!

🎯 Common Patterns

Here are patterns you’ll use daily:

from fastapi import FastAPI
from pydantic import BaseModel
from typing import Optional

app = FastAPI()

# 🏗️ Pattern 1: Request Models
class Product(BaseModel):
    name: str          # 📦 Product name
    price: float       # 💰 Product price
    is_offer: Optional[bool] = None  # 🏷️ Special offer?

# 🎨 Pattern 2: POST endpoints
@app.post("/products/")
def create_product(product: Product):
    return {"message": f"Created {product.name}! 🎉", "product": product}

# 🔄 Pattern 3: Query parameters
@app.get("/items/")
def read_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit, "items": [f"Item {i} 📦" for i in range(skip, skip + limit)]}

💡 Practical Examples

🛒 Example 1: E-Commerce API

Let’s build something real:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List, Optional
from datetime import datetime

app = FastAPI(title="ShopAPI 🛒", version="1.0.0")

# 🛍️ Define our models
class Product(BaseModel):
    id: int
    name: str
    price: float
    description: Optional[str] = None
    emoji: str  # Every product needs an emoji! 

class CartItem(BaseModel):
    product_id: int
    quantity: int

class ShoppingCart(BaseModel):
    user_id: int
    items: List[CartItem] = []
    created_at: datetime = datetime.now()

# 💾 In-memory storage (for demo)
products_db = {
    1: Product(id=1, name="Python Book", price=29.99, emoji="📘", description="Learn Python the fun way!"),
    2: Product(id=2, name="Coffee Mug", price=12.99, emoji="☕", description="For late-night coding"),
    3: Product(id=3, name="Mechanical Keyboard", price=89.99, emoji="⌨️", description="Click-clack your way to success")
}

carts = {}

# 📋 List all products
@app.get("/products/", response_model=List[Product])
def get_products():
    """Get all available products 🛍️"""
    return list(products_db.values())

# 🔍 Get specific product
@app.get("/products/{product_id}", response_model=Product)
def get_product(product_id: int):
    """Get details of a specific product 📦"""
    if product_id not in products_db:
        raise HTTPException(status_code=404, detail="Product not found 😢")
    return products_db[product_id]

# 🛒 Create shopping cart
@app.post("/carts/", response_model=ShoppingCart)
def create_cart(user_id: int):
    """Create a new shopping cart 🛒"""
    cart = ShoppingCart(user_id=user_id)
    carts[user_id] = cart
    return cart

# ➕ Add item to cart
@app.post("/carts/{user_id}/items/")
def add_to_cart(user_id: int, item: CartItem):
    """Add an item to the cart 🎁"""
    if user_id not in carts:
        raise HTTPException(status_code=404, detail="Cart not found! Create one first 🛒")
    
    if item.product_id not in products_db:
        raise HTTPException(status_code=404, detail="Product not found 😢")
    
    carts[user_id].items.append(item)
    product = products_db[item.product_id]
    return {"message": f"Added {item.quantity}x {product.emoji} {product.name} to cart! 🎉"}

# 💰 Calculate total
@app.get("/carts/{user_id}/total")
def calculate_total(user_id: int):
    """Calculate cart total 💰"""
    if user_id not in carts:
        raise HTTPException(status_code=404, detail="Cart not found 😢")
    
    total = 0.0
    for item in carts[user_id].items:
        product = products_db[item.product_id]
        total += product.price * item.quantity
    
    return {"total": total, "message": f"Total: ${total:.2f} 💸"}

🎯 Try it yourself: Add a remove_from_cart endpoint and a discount system!

🎮 Example 2: Game Score API

Let’s make it fun:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List, Dict
from datetime import datetime
from enum import Enum

app = FastAPI(title="GameScore API 🎮", version="1.0.0")

# 🏆 Game types
class GameType(str, Enum):
    PUZZLE = "puzzle"
    ACTION = "action"
    STRATEGY = "strategy"

# 🎯 Score model
class Score(BaseModel):
    player_name: str
    score: int
    game_type: GameType
    timestamp: datetime = datetime.now()
    achievements: List[str] = []

# 💾 Leaderboard storage
leaderboards: Dict[GameType, List[Score]] = {
    GameType.PUZZLE: [],
    GameType.ACTION: [],
    GameType.STRATEGY: []
}

# 🎮 Submit a score
@app.post("/scores/")
def submit_score(score: Score):
    """Submit a new game score 🎯"""
    # Add achievements based on score
    if score.score >= 1000:
        score.achievements.append("🏆 Champion")
    if score.score >= 500:
        score.achievements.append("⭐ Expert")
    if score.score >= 100:
        score.achievements.append("🌟 Rising Star")
    
    # Add to leaderboard
    leaderboards[score.game_type].append(score)
    leaderboards[score.game_type].sort(key=lambda x: x.score, reverse=True)
    
    # Keep only top 10
    leaderboards[score.game_type] = leaderboards[score.game_type][:10]
    
    return {
        "message": f"Score submitted! {score.player_name} scored {score.score} points! 🎉",
        "achievements": score.achievements
    }

# 📊 Get leaderboard
@app.get("/leaderboard/{game_type}")
def get_leaderboard(game_type: GameType, top: int = 5):
    """Get the top players 🏆"""
    scores = leaderboards[game_type][:top]
    
    return {
        "game_type": game_type,
        "leaderboard": [
            {
                "rank": i + 1,
                "player": score.player_name,
                "score": score.score,
                "emoji": "🥇" if i == 0 else "🥈" if i == 1 else "🥉" if i == 2 else "🏅"
            }
            for i, score in enumerate(scores)
        ]
    }

# 🎲 Random challenge
@app.get("/challenge/")
def get_challenge():
    """Get today's challenge 🎲"""
    import random
    
    challenges = [
        {"challenge": "Score over 500 in Puzzle mode!", "reward": "🧩 Puzzle Master"},
        {"challenge": "Win 3 Action games in a row!", "reward": "⚡ Speed Demon"},
        {"challenge": "Reach 1000 points in Strategy!", "reward": "🧠 Strategic Mind"}
    ]
    
    return random.choice(challenges)

🚀 Advanced Concepts

🧙‍♂️ Advanced Topic 1: Dependency Injection

When you’re ready to level up, try this advanced pattern:

from fastapi import FastAPI, Depends, Header, HTTPException
from typing import Optional

app = FastAPI()

# 🎯 Advanced dependency
async def verify_token(x_token: Optional[str] = Header(None)):
    """Verify API token 🔐"""
    if x_token != "secret-token":
        raise HTTPException(status_code=403, detail="Invalid token 🚫")
    return x_token

# 🪄 Using dependencies
@app.get("/protected/", dependencies=[Depends(verify_token)])
async def protected_route():
    return {"message": "Welcome to the secret area! 🎭"}

# 🚀 Dependency with data
async def get_current_user(token: str = Depends(verify_token)):
    # In real app, decode token to get user
    return {"username": "fastapi_wizard", "emoji": "🧙‍♂️"}

@app.get("/me/")
async def read_me(current_user: dict = Depends(get_current_user)):
    return {"message": f"Hello {current_user['username']} {current_user['emoji']}!"}

🏗️ Advanced Topic 2: Background Tasks

For the brave developers:

from fastapi import FastAPI, BackgroundTasks
import time

app = FastAPI()

# 🚀 Background task function
def send_notification(email: str, message: str):
    """Simulate sending email 📧"""
    time.sleep(2)  # Simulate slow operation
    print(f"📧 Email sent to {email}: {message}")

# 🎯 Endpoint with background task
@app.post("/send-notification/")
async def create_notification(
    email: str, 
    background_tasks: BackgroundTasks
):
    # Add task to background
    background_tasks.add_task(
        send_notification, 
        email, 
        "Your API request was processed! 🎉"
    )
    
    return {"message": "Notification will be sent soon! 📬"}

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Forgetting Async/Await

# ❌ Wrong way - mixing sync and async incorrectly
@app.get("/users/{user_id}")
async def get_user(user_id: int):
    time.sleep(1)  # 💥 This blocks the event loop!
    return {"user_id": user_id}

# ✅ Correct way - use async properly
import asyncio

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    await asyncio.sleep(1)  # ✅ Non-blocking!
    return {"user_id": user_id}

🤯 Pitfall 2: Wrong Status Codes

# ❌ Dangerous - returning 200 for errors!
@app.post("/items/")
def create_item(name: str):
    if len(name) < 3:
        return {"error": "Name too short"}  # 💥 Still returns 200 OK!
    
# ✅ Safe - use proper exceptions!
from fastapi import HTTPException

@app.post("/items/")
def create_item(name: str):
    if len(name) < 3:
        raise HTTPException(
            status_code=400, 
            detail="Name must be at least 3 characters! 📏"
        )
    return {"message": f"Created {name}! ✅"}

🛠️ Best Practices

🎯 Use Type Hints: Always specify types for automatic validation!
📝 Document Your APIs: Use docstrings - they appear in auto-docs
🛡️ Handle Errors Gracefully: Use HTTPException for clear error messages
🎨 Organize with Routers: Split large APIs into multiple files
✨ Keep It Simple: Don’t over-engineer - FastAPI does a lot for you!

🧪 Hands-On Exercise

🎯 Challenge: Build a Task Management API

Create a complete task management system:

📋 Requirements:

✅ CRUD operations for tasks (Create, Read, Update, Delete)
🏷️ Task categories (work, personal, urgent)
👤 User assignment feature
📅 Due dates with filtering
🎨 Each task needs a status emoji!

🚀 Bonus Points:

Add task search functionality
Implement priority sorting
Create statistics endpoint

💡 Solution

🔍 Click to see solution

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List, Optional
from datetime import datetime, date
from enum import Enum

app = FastAPI(title="TaskMaster API 📋")

# 🎯 Our models
class TaskStatus(str, Enum):
    TODO = "todo"
    IN_PROGRESS = "in_progress"
    DONE = "done"

class TaskCategory(str, Enum):
    WORK = "work"
    PERSONAL = "personal"
    URGENT = "urgent"

class Task(BaseModel):
    id: Optional[int] = None
    title: str
    description: Optional[str] = None
    status: TaskStatus = TaskStatus.TODO
    category: TaskCategory
    due_date: Optional[date] = None
    assigned_to: Optional[str] = None
    created_at: datetime = datetime.now()

    def get_emoji(self) -> str:
        """Get status emoji 🎨"""
        emoji_map = {
            TaskStatus.TODO: "📝",
            TaskStatus.IN_PROGRESS: "🔄",
            TaskStatus.DONE: "✅"
        }
        return emoji_map[self.status]

# 💾 Storage
tasks_db: List[Task] = []
task_counter = 1

# ➕ Create task
@app.post("/tasks/", response_model=Task)
def create_task(task: Task):
    """Create a new task 📝"""
    global task_counter
    task.id = task_counter
    task_counter += 1
    tasks_db.append(task)
    return task

# 📋 Get all tasks
@app.get("/tasks/", response_model=List[Task])
def get_tasks(
    category: Optional[TaskCategory] = None,
    status: Optional[TaskStatus] = None,
    assigned_to: Optional[str] = None
):
    """Get all tasks with optional filters 🔍"""
    filtered_tasks = tasks_db
    
    if category:
        filtered_tasks = [t for t in filtered_tasks if t.category == category]
    if status:
        filtered_tasks = [t for t in filtered_tasks if t.status == status]
    if assigned_to:
        filtered_tasks = [t for t in filtered_tasks if t.assigned_to == assigned_to]
    
    return filtered_tasks

# 🔍 Get specific task
@app.get("/tasks/{task_id}", response_model=Task)
def get_task(task_id: int):
    """Get a specific task by ID 🎯"""
    task = next((t for t in tasks_db if t.id == task_id), None)
    if not task:
        raise HTTPException(status_code=404, detail="Task not found 😢")
    return task

# 🔄 Update task
@app.put("/tasks/{task_id}", response_model=Task)
def update_task(task_id: int, updated_task: Task):
    """Update an existing task ✏️"""
    for i, task in enumerate(tasks_db):
        if task.id == task_id:
            updated_task.id = task_id
            updated_task.created_at = task.created_at
            tasks_db[i] = updated_task
            return updated_task
    raise HTTPException(status_code=404, detail="Task not found 😢")

# 🗑️ Delete task
@app.delete("/tasks/{task_id}")
def delete_task(task_id: int):
    """Delete a task 🗑️"""
    for i, task in enumerate(tasks_db):
        if task.id == task_id:
            del tasks_db[i]
            return {"message": f"Task {task_id} deleted! 🗑️"}
    raise HTTPException(status_code=404, detail="Task not found 😢")

# 📊 Get statistics
@app.get("/stats/")
def get_stats():
    """Get task statistics 📊"""
    total = len(tasks_db)
    if total == 0:
        return {"message": "No tasks yet! Start creating some 🚀"}
    
    stats = {
        "total_tasks": total,
        "by_status": {
            "📝 Todo": len([t for t in tasks_db if t.status == TaskStatus.TODO]),
            "🔄 In Progress": len([t for t in tasks_db if t.status == TaskStatus.IN_PROGRESS]),
            "✅ Done": len([t for t in tasks_db if t.status == TaskStatus.DONE])
        },
        "by_category": {
            "💼 Work": len([t for t in tasks_db if t.category == TaskCategory.WORK]),
            "🏠 Personal": len([t for t in tasks_db if t.category == TaskCategory.PERSONAL]),
            "🚨 Urgent": len([t for t in tasks_db if t.category == TaskCategory.URGENT])
        },
        "completion_rate": f"{len([t for t in tasks_db if t.status == TaskStatus.DONE]) / total * 100:.1f}%"
    }
    
    return stats

# 🔍 Search tasks
@app.get("/search/")
def search_tasks(q: str):
    """Search tasks by title or description 🔍"""
    results = [
        task for task in tasks_db
        if q.lower() in task.title.lower() or 
        (task.description and q.lower() in task.description.lower())
    ]
    
    return {
        "query": q,
        "count": len(results),
        "results": results
    }

🎓 Key Takeaways

You’ve learned so much! Here’s what you can now do:

✅ Create FastAPI applications with confidence 💪
✅ Define API endpoints with automatic validation 🛡️
✅ Use Pydantic models for data validation 🎯
✅ Handle errors properly with HTTPException 🐛
✅ Build real-world APIs with FastAPI! 🚀

Remember: FastAPI makes API development fast, fun, and reliable! It’s your friend in building modern Python web services. 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered FastAPI basics!

Here’s what to do next:

💻 Practice with the exercises above
🏗️ Build a complete API project
📚 Explore FastAPI’s advanced features (WebSockets, GraphQL)
🌟 Deploy your API to the cloud!

Remember: Every API expert started with their first endpoint. Keep coding, keep learning, and most importantly, have fun building amazing APIs! 🚀

Happy API building! 🎉🚀✨

Prerequisites

What you'll learn