FastAPI Basics: Build Your First Python API in Minutes

# Install first: pip install fastapi uvicorn
# Run with:    uvicorn hello_api:app --reload

from fastapi import FastAPI

# FastAPI() creates the application instance.
# Think of it as 'opening the restaurant for business.'
app = FastAPI(
    title="TheCodeForge Demo API",
    description="A minimal FastAPI example that proves how little code you need.",
    version="1.0.0"
)

# The @app.get decorator registers this function as the handler
# for HTTP GET requests to the root path "/".
@app.get("/")
def read_root() -> dict:
    # FastAPI converts Python dicts to JSON automatically.
    return {"message": "Welcome to TheCodeForge API", "status": "running"}

# A second endpoint at /health — useful for monitoring tools
@app.get("/health")
def health_check() -> dict:
    return {"healthy": True}

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
from typing import Optional

app = FastAPI(title="Bookstore API")

# --- Pydantic Model ---
class Book(BaseModel):
    title: str = Field(..., min_length=1, max_length=200)
    author: str = Field(..., min_length=2)
    year: int = Field(..., ge=1000, le=2100)
    genre: Optional[str] = None

books_db: dict[int, Book] = {
    1: Book(title="Clean Code", author="Robert C. Martin", year=2008, genre="Software Engineering"),
}
next_id = 2

# --- PATH PARAMETER ---
@app.get("/books/{book_id}")
def get_book(book_id: int) -> Book:
    if book_id not in books_db:
        raise HTTPException(status_code=404, detail=f"Book {book_id} not found")
    return books_db[book_id]

# --- QUERY PARAMETERS ---
@app.get("/books")
def list_books(genre: Optional[str] = None, limit: int = 10) -> list[Book]:
    all_books = list(books_db.values())
    if genre:
        all_books = [b for b in all_books if b.genre and b.genre.lower() == genre.lower()]
    return all_books[:limit]

# --- REQUEST BODY ---
@app.post("/books", status_code=201)
def create_book(new_book: Book) -> dict:
    global next_id
    books_db[next_id] = new_book
    created_id = next_id
    next_id += 1
    return {"message": "Book created successfully", "id": created_id}

import httpx
from fastapi import FastAPI, Depends, Header, HTTPException
from typing import Annotated

app = FastAPI(title="Async + DI Demo")

def require_api_key(x_api_key: Annotated[str | None, Header()] = None) -> str:
    if x_api_key != "forge-secret-key-123":
        raise HTTPException(status_code=403, detail="Invalid API key")
    return x_api_key

@app.get("/external-quote")
async def fetch_random_quote(api_key: Annotated[str, Depends(require_api_key)]) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.get("https://api.quotable.io/random")
    
    if response.status_code != 200:
        raise HTTPException(status_code=502, detail="Upstream failure")
    
    data = response.json()
    return {"quote": data.get("content"), "author": data.get("author")}

from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import JSONResponse

app = FastAPI(title="Custom Errors")

class InsufficientFundsError(Exception):
    def __init__(self, balance: float, needed: float):
        self.balance = balance
        self.needed = needed

@app.exception_handler(InsufficientFundsError)
async def insufficient_funds_handler(request: Request, exc: InsufficientFundsError):
    return JSONResponse(
        status_code=402,
        content={
            "error": "insufficient_funds",
            "balance": exc.balance,
            "needed": exc.needed,
            "message": f"Need {exc.needed} but only have {exc.balance}"
        }
    )

@app.get("/withdraw/{amount}")
async def withdraw(amount: float):
    balance = 100.0
    if amount > balance:
        raise InsufficientFundsError(balance=balance, needed=amount)
    return {"withdrawn": amount, "remaining": balance - amount}

from fastapi.testclient import TestClient
from io.thecodeforge.basics.book_api import app

client = TestClient(app)

def test_get_book_by_id():
    response = client.get("/books/1")
    assert response.status_code == 200
    data = response.json()
    assert data["title"] == "Clean Code"

def test_get_book_not_found():
    response = client.get("/books/999")
    assert response.status_code == 404
    assert "not found" in response.json()["detail"]

def test_create_book_invalid_year():
    response = client.post("/books", json={
        "title": "Bad", "author": "Me", "year": 500
    })
    assert response.status_code == 422
    errors = response.json()["detail"]
    assert any(err["loc"] == ["body", "year"] for err in errors)

def test_list_books_with_genre_filter():
    response = client.get("/books?genre=Software Engineering&limit=1")
    assert response.status_code == 200
    data = response.json()
    assert len(data) == 1