FastAPI Basics: Build Your First Python API in Minutes

APIs are the invisible glue holding the modern internet together. Every time your phone checks the weather, a payment processes, or a recommendation pops up on a streaming service, an API responded to a request in milliseconds. Python has several frameworks for building those APIs, but FastAPI has quietly become the one serious backend teams reach for first — and for very good reason.

Before FastAPI, Python developers were stuck with a trade-off: Flask was simple but required mountains of boilerplate for validation and docs, while Django REST Framework was powerful but heavy. FastAPI solved both problems by leaning on Python's own type hints to validate data automatically, generate interactive documentation instantly, and handle concurrent requests without blocking — all in a framework that reads almost like plain English.

By the end of this article you'll have built a fully working REST API with typed request bodies, path and query parameters, automatic validation, and interactive docs you can test in your browser. You'll understand not just how FastAPI works, but why each design decision exists — which is the knowledge that makes you dangerous in an interview room or a production codebase.

Why FastAPI Exists — and Why It Beats Flask for New Projects

Flask was designed in 2010. Python type hints didn't exist until 2015. Async/await didn't land until Python 3.5. Flask was never built with these features in mind, so adding them feels like bolting wings onto a car.

FastAPI was designed in 2018 specifically around type hints and the ASGI (Asynchronous Server Gateway Interface) standard. That's not just a version number difference — it's a completely different philosophy. When you write a type hint in FastAPI, the framework actually reads it at startup and uses it to validate incoming data, serialize outgoing data, and generate documentation. You write the types once and get three things for free.

The performance difference is real too. Because FastAPI is ASGI-native and supports Python's async/await, it can handle thousands of simultaneous I/O-bound requests without spawning new threads. Benchmarks consistently put it alongside Node.js and Go for throughput — which is extraordinary for Python.

Use FastAPI when you're building a new API from scratch, especially if your endpoints touch databases, external services, or any I/O. Use Flask if you're maintaining an existing Flask codebase or need a tiny one-file script server where the overhead of learning something new isn't worth it.

# 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}

Path Parameters, Query Parameters, and Pydantic Request Bodies

Every API needs to accept input. FastAPI gives you three clean ways to do it, each suited to a different purpose — and confusing them is one of the most common beginner mistakes.

Path parameters are part of the URL itself: /users/42 where 42 is the user ID. They identify a specific resource. Query parameters come after the ? in the URL: /products?category=books&limit=10. They filter, sort, or paginate a collection. Request bodies are sent in the HTTP body (usually as JSON) and carry complex structured data.

FastAPI's magic is that you declare all three using nothing but Python function signatures. A path parameter is a function argument that matches a {placeholder} in the route. A query parameter is a function argument that doesn't match any placeholder. A request body is a function argument typed as a Pydantic model.

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}

Async Endpoints and Dependency Injection — Where FastAPI Really Shines

Use async def when your endpoint does I/O — database queries, HTTP calls to external APIs, reading files. These operations spend most of their time waiting, not computing. With async def, FastAPI can handle other requests during that wait instead of blocking a thread. Use plain def when your endpoint does CPU-heavy work — image processing, complex calculations. FastAPI runs those in a thread pool automatically.

Dependency Injection (DI) is FastAPI's answer to sharing reusable logic. You write a function that produces a value, declare it with Depends(), and FastAPI calls it automatically before your endpoint runs.

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")}

Frequently Asked Questions