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 "/".
# FastAPI reads the return type hint (dict) to know how to serialize the response.
@app.get("/")
def read_root() -> dict:
    # Whatever you return from this function becomes the JSON response body.
    # FastAPI converts Python dicts to JSON automatically.
    return {"message": "Welcome to TheCodeForge API", "status": "running"}

# A second endpoint at /health — useful for load balancers and monitoring tools
# that need to confirm your service is alive.
@app.get("/health")
def health_check() -> dict:
    return {"healthy": True}

# pip install fastapi uvicorn pydantic
# Run: uvicorn book_api:app --reload

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

app = FastAPI(title="Bookstore API")

# --- Pydantic Model ---
# This class defines the exact shape of data expected when creating a book.
# Pydantic validates every field automatically. If 'year' arrives as "banana",
# FastAPI returns a 422 error with a human-readable message — no try/except needed.
class Book(BaseModel):
    title: str = Field(..., min_length=1, max_length=200, description="The book's full title")
    author: str = Field(..., min_length=2, description="Full name of the author")
    year: int = Field(..., ge=1000, le=2100, description="Year of publication")
    genre: Optional[str] = Field(default=None, description="Genre is optional")

# Fake in-memory database — in a real app this would be PostgreSQL, MongoDB, etc.
books_db: dict[int, Book] = {
    1: Book(title="Clean Code", author="Robert C. Martin", year=2008, genre="Software Engineering"),
    2: Book(title="The Pragmatic Programmer", author="David Thomas", year=1999, genre="Software Engineering"),
}
next_id = 3  # Simple ID counter for demo purposes

# --- PATH PARAMETER ---
# The {book_id} in the URL maps directly to the book_id argument.
# FastAPI automatically converts the string from the URL to an int.
# If someone passes /books/abc, FastAPI returns a 422 before this function runs.
@app.get("/books/{book_id}")
def get_book(book_id: int) -> Book:
    # HTTPException is FastAPI's way of returning HTTP error responses.
    # Raising it immediately stops execution and sends the error to the client.
    if book_id not in books_db:
        raise HTTPException(status_code=404, detail=f"Book with ID {book_id} not found")
    return books_db[book_id]

# --- QUERY PARAMETERS ---
# genre and limit are NOT in the URL path, so FastAPI treats them as query params.
# Example call: GET /books?genre=Software Engineering&limit=5
# 'limit' has a default value of 10, so it's optional in the request.
@app.get("/books")
def list_books(genre: Optional[str] = None, limit: int = 10) -> list[Book]:
    all_books = list(books_db.values())

    # Filter by genre only if the caller provided one
    if genre:
        all_books = [b for b in all_books if b.genre and b.genre.lower() == genre.lower()]

    # Slice the list to respect the limit
    return all_books[:limit]

# --- REQUEST BODY ---
# Because 'new_book' is typed as a Pydantic model (not a simple type),
# FastAPI knows to read it from the HTTP request body, not the URL.
@app.post("/books", status_code=201)  # 201 Created is the correct HTTP status for resource creation
def create_book(new_book: Book) -> dict:
    global next_id
    books_db[next_id] = new_book
    created_id = next_id
    next_id += 1
    # Return a confirmation with the assigned ID so the client can reference it later
    return {"message": "Book created successfully", "id": created_id, "book": new_book}

# pip install fastapi uvicorn httpx
# Run: uvicorn async_book_api:app --reload

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

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

# ─── DEPENDENCY: API Key Validator ───────────────────────────────────────────
# This function is a dependency. It extracts the X-API-Key header and validates it.
# Any endpoint that needs authentication just declares this as a dependency.
# FastAPI calls it automatically before the endpoint function runs.
def require_api_key(x_api_key: Annotated[str | None, Header()] = None) -> str:
    # In production, you'd check this against a database or secrets manager.
    valid_keys = {"forge-secret-key-123", "forge-secret-key-456"}

    if x_api_key not in valid_keys:
        # Raising HTTPException inside a dependency works exactly like inside an endpoint.
        # FastAPI intercepts it and returns the 403 response — the endpoint never runs.
        raise HTTPException(
            status_code=403,
            detail="Invalid or missing API key. Include X-API-Key header."
        )
    return x_api_key  # Return the key so the endpoint knows which client called it

# ─── DEPENDENCY: Pagination Parameters ───────────────────────────────────────
# Reusable pagination logic. Instead of copying skip/limit params into every
# list endpoint, we define them once here and inject them everywhere they're needed.
def pagination_params(skip: int = 0, limit: int = 10) -> dict:
    # We could add validation here — e.g., raise an error if limit > 100
    if limit > 100:
        raise HTTPException(status_code=400, detail="limit cannot exceed 100")
    return {"skip": skip, "limit": limit}

# ─── ASYNC ENDPOINT: Fetches data from an external API ───────────────────────
# async def is correct here because httpx.AsyncClient.get() is an I/O operation.
# While waiting for the external API to respond, FastAPI can serve other requests.
# If this were a plain def, it would block the entire server during the network wait.
@app.get("/external-quote")
async def fetch_random_quote(
    api_key: Annotated[str, Depends(require_api_key)]  # DI: validates key before we even start
) -> dict:
    # httpx is an async-compatible HTTP client — the FastAPI equivalent of requests.
    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 quote service is unavailable")

    data = response.json()
    return {
        "quote": data.get("content"),
        "author": data.get("author"),
        "fetched_by_key": api_key  # Shows which API key made the request (useful for logging)
    }

# ─── SYNC ENDPOINT WITH SHARED PAGINATION DEPENDENCY ─────────────────────────
# This endpoint does no I/O of its own (just slicing a list), so plain def is fine.
# Both require_api_key and pagination_params are injected — FastAPI resolves both.
@app.get("/catalogue")
def get_catalogue(
    api_key: Annotated[str, Depends(require_api_key)],
    pagination: Annotated[dict, Depends(pagination_params)]
) -> dict:
    full_catalogue = [f"Item {i}" for i in range(1, 51)]  # Simulates 50 database records

    skip = pagination["skip"]
    limit = pagination["limit"]
    page = full_catalogue[skip: skip + limit]  # Apply pagination slice

    return {
        "total_items": len(full_catalogue),
        "skip": skip,
        "limit": limit,
        "results": page
    }