Introduction to FastAPI

Session 1: Core Objects

Figure: A sleek, futuristic high-speed train or hyperloop pod arriving at a platform. The platform is clean and modern. With speed lines indicating high performance.

1. The FastAPI class
2. The request class
3. The Request Parameters: from fastapi import Body, Cookie, File, Form, Header, Path, Query
4. The response class
5. The Custom Response Classes
6. The APIRouter class

• Hook: In Module 1, we talked about the “Server” as a concept—a machine that listens and responds.
• Today, we are going to look at the tool you will use to build that server: FastAPI.
• Lay of the Land: We will break this module into two main sessions:
  1. Core Objects: The raw building blocks (The “Lego bricks”).
  2. Types & Validation: The “glue” and “safety checks” that make FastAPI special.
• Think of this session as “Meeting the Cast” of a play before we see the performance.

1. The FastAPI Class

from fastapi import FastAPI

app = FastAPI()

@app.get("/items")
def get_items():
    return [1, 2, 3]

The FastAPI class is the main entry point for your application. It inherits from Starlette and acts as the central hub where you:

• Register routes using decorators like @app.get(), @app.post(), ..etc.
• Configure global settings like exception handlers (404, 500, ..etc.).
• Manage lifecycles: events such as: startup and shutdown

• M1 Connection (Verbs): Remember those HTTP Verbs? GET, POST, PUT?

• Concept: The @app.get() decorator is how we implement an HTTP Verb in Python. You are literally telling the server: “When you hear a GET request at this path, run this function.”

• The app object is the “Brain” of your server. It holds the map (Routing Table) of where every request should go.

• Manage lifecycles: events such as:

  • startup (e.g., connect to db)
  • and shutdown (e.g., disconnect from db).

2. The Request Class

Figure: A diagram showing the flow of an HTTP request. A data packet labeled ‘Request’ enters a funnel labeled ‘FastAPI’. The funnel splits the packet into ‘Head’ (Metadata) and ‘Body’ (Payload).

from fastapi import Request

The Request class provides direct access to the underlying HTTP request. This is useful when you need to access:

• The client’s IP address.
• Raw Headers or Cookies.
• The request Body as a raw stream.

• M1 Connection (The Message): Recall the “Envelope vs. Contents” metaphor?
• The Request object gives you raw access to the entire envelope.
• Usually, FastAPI opens it for you (as we’ll see next), but sometimes you need to check the postmark (Client IP) or read a raw message directly.
• Use Case: Rate limiting (checking IP) or logging incoming traffic.

3. Request Parameters

from fastapi import Body, Cookie, File, Form, Header, Path, Query

These are the special functions that you can put in path operation function parameters or dependency functions with Annotated to get data from the request.

• Path & Query: For values in the URL or query string.
• Body, Form, & File: For data, form fields, or files sent in the request payload.
• Header & Cookie: For extracting metadata from the request.

• M1 Connection (URL Anatomy): This is where theory meets practice.
• Path params map to the Resource Location (The “What”).
• Query params map to the Parameters (The “How”).
• Header params let you read the Metadata (e.g., Auth tokens or User-Agent).
• Feature: FastAPI automatically splits the URL string into these clean Python variables for you. You don’t parse strings; you just ask for variables.

4. The Response Class

Figure: A diagram showing the output of the FastAPI funnel. Data comes out and is packaged into a box labeled ‘Response’. A label is being attached to the box that says ‘Status: 200 OK’.

from fastapi import Response

You can declare a parameter in a path operation function or dependency to be of type Response and then you can set data for the response like headers or cookies.

• Set custom HTTP status codes (e.g., 201 Created).
• Add custom headers or set cookies.
• Return different types of content, such as JSON, HTML, or plain text.

• M1 Connection (Status Codes): Remember the traffic lights (200, 404, 500)?
• This object is how you control those lights.
• By default, FastAPI returns 200 OK. But if you are creating a resource, you might want to manually set 201 Created.
• This is also where you set Cookies (the “VIP badge” for state) to send back to the user.

5. Custom Response Classes

from fastapi.responses import (
    FileResponse,
    HTMLResponse,
    JSONResponse,
    ORJSONResponse,
    PlainTextResponse,
    RedirectResponse,
    Response,
    StreamingResponse,
    UJSONResponse,
)

Read more about it in the FastAPI docs for Custom Response - HTML, Stream, File, others.

Status Codes

from fastapi import status

It contains a group of named constants (variables) with integer status codes. For example:

• 200: status.HTTP_200_OK
• 403: status.HTTP_403_FORBIDDEN
• etc.

Read more about it in the FastAPI docs about Response Status Code.

It can be convenient to quickly access HTTP (and WebSocket) status codes in your app, using autocompletion for the name without having to remember the integer status codes by memory.

6. The APIRouter Class

from fastapi import APIRouter

Group path operations, for example to structure an app in multiple files: routers/items.py and routers/users.py:

.
├── app
│   ├── __init__.py
│   ├── main.py
│   └── routers
│   │   ├── __init__.py
│   │   ├── items.py
│   │   └── users.py

Read more about it in the FastAPI docs for Bigger Applications - Multiple Files.

Running FastAPI: Development

To start your API in development mode, use the command:

fastapi dev main.py

• Mode: Development
• Auto-reload: Enabled (Server restarts when code changes).
• Host: 127.0.0.1 (Localhost).
• Warning: This mode is resource-intensive and less stable. Do not use in production.

• Concept: The “Workshop”.
• fastapi dev is for you, the developer.
• It watches your files. If you save a change, the server reloads instantly so you can test it.
• It locks the doors (only listens to localhost), so no one from the outside internet can access your broken, half-written code.

Running FastAPI: Production

To start your API in production mode, use the command:

fastapi run main.py

• Mode: Production
• Auto-reload: Disabled (Stable, maximizing performance).
• Host: 0.0.0.0 (Listen on all available IP addresses).
• Termination Proxy: Typically runs behind an HTTPS proxy (like Nginx or a Load Balancer).

• Concept: The “Stage”.
• fastapi run is for the world.
• It maximizes stability and performance. It doesn’t waste energy watching files.
• It opens the doors (0.0.0.0) so the container or internet can reach it.
• Important: In real deployments, you usually put a “Bodyguard” (Termination Proxy) in front of it to handle HTTPS encryption.

FastAPI: Standing on Giants

FastAPI is not built from scratch. It creates a powerful synergy by combining two best-in-class libraries:

1. Starlette: For the web parts.
2. Pydantic: For the data parts.

• Concept: FastAPI is a “Glue Framework”.
• It doesn’t re-invent the wheel. It takes the fastest web server (Starlette) and the best data validator (Pydantic) and wraps them in a unified, developer-friendly API.
• You get the speed of Starlette and the safety of Pydantic without having to wire them together yourself.

Starlette: The Web Engine

Starlette provides the underlying web capabilities:

• Asynchronous Core: Built on anyio, allowing for high concurrency (dealing with many users at once).
• WebSockets: Native support for real-time bi-directional communication.

• Analogy: If FastAPI is the car, Starlette is the Engine.
• It handles the raw HTTP bytes, the connections, and the async event loop.
• Features like “Background Tasks” (sending an email after a user signs up) come directly from Starlette.
• When you use FastAPI(), you are actually creating a Starlette app with extra superpowers.

Pydantic: The Data Enforcer

Pydantic provides the data validation and serialization:

Figure: the BaseModel

• Enforces that input data matches your defined types: "123" \(\rightarrow\) 123
• Written in Rust (v2), making it one of the fastest validators available.
• It also draws the map (OpenAPI/Swagger UI) based on your Python code.

• The shape-sorter itself represents your Pydantic Model (Schema).

• A structure that defines the expected “shapes” (data types) of your inputs.

• Analogy: If Starlette is the Engine, Pydantic is the Security System.

• It checks every piece of data entering the car.

• It’s not just checking errors; it’s fixing data (Parsing).

Extra: The Linguistic Origin

The name is a portmanteau of Py (for Python) and pedantic.

In English, a “pedantic” person is someone who is excessively concerned with minor details, rules, or formalisms. In the context of programming, being “pedantic” usually has a negative connotation, implying that a tool or person is being needlessly difficult about small syntax errors or strict types.

Key Takeaways

• FastAPI Class: The central hub for routing, configuration, and application lifecycle.
• Request & Response: Use Request for raw access to headers/IPs and Response to manually control status codes and cookies.
• Modular Routing: APIRouter allows you to split large applications into manageable, logical files.
• Dev vs. Prod: fastapi dev enables auto-reload for local iteration; fastapi run optimizes for performance and security in production.
• The “Giants”: FastAPI combines Starlette (for high-concurrency async performance) and Pydantic (for strict, automated data validation and documentation).

Session 2: Syntax and Semantics

Decorators: The @ Symbol

A Decorator is a function that takes another function and extends its behavior without explicitly modifying it.

@app.get("/items")
def get_items():
    return ["a", "b"]

In FastAPI: The @app.get decorator tells FastAPI: “Take the function below (get_items) and register it in the Routing Table for the path /items.”

• Concept: The “Wrapper”.
• Imagine wrapping a gift. The gift (your function) stays the same, but the wrapping (the decorator) adds a label saying “To: /users”.
• M1 Connection: This is how we map a URL Resource (M1 Lesson 2) to a Python Function.
• Without the decorator, get_items is just a standard Python function that does nothing on the web. The decorator “activates” it for the web server.

Type Hints Matter

Type hints are the single definition that drives three separate systems:

1. Validation & Parsing
2. Documentation
3. Auto-completion

Unlike standard Python where type hints are usually ignored at runtime, FastAPI reads them to execute logic.

• Hook: Standard Python ignores types at runtime. FastAPI enforces them.
• M1 Connection (The Contract): In M1, we talked about “Content Negotiation” (e.g., “I speak JSON”).
• Type Hints are how you define that contract in code.
• If you say item_id: int, FastAPI builds a Gatekeeper that physically stops any request that sends text instead of a number.
• It validates (Checks), Converts (String “10” -> Int 10), and Documents (Tells the world “I need an Int”) all from one word.

Without Types

Manual Parsing:

def create_item(request):
    data = request.json
    
    # 1. Manually check existence
    if "price" not in data:
        return {"error": "Price is required"}, 400
        
    # 2. Manually check type
    if not isinstance(data["price"], (int, float)):
        return {"error": "Price must be a number"}, 400
        
    # 3. Manually parse/convert
    price = float(data["price"])
    
    # ... finally business logic ...

• Pain Point: This is the “Bad Old Days” of defensive coding.
• Look at this code. The “Business Logic” is one line at the end.
• The rest? Boilerplate Validation.
• You are manually checking: “Is it there?”, “Is it a number?”, “Can I convert it?”.
• Risk: If you forget one check, your app crashes or acts unpredictably.

With Type Hints

In FastAPI, you declare the type in the function signature. The framework inspects these signatures at runtime.

from fastapi import FastAPI

app = FastAPI()

# FastAPI reads 'float' and handles validation/conversion for you
@app.post("/items/")
async def create_item(price: float):
    # 'price' is guaranteed to be a float here.
    return {"price_with_tax": price * 1.2}

• Declaration: price: float tells FastAPI everything it needs to know.
• Automatic Parsing: It converts the payload to a float automatically.
• Automatic 422 Errors: If the user sends “ten”, FastAPI returns a standard error response detailing exactly where the validation failed.

Complex Data Structures (Pydantic Models)

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    tags: list[str] = [] # Optional list of strings

@app.post("/items/")
async def create_item(item: Item): 
    # FastAPI validates the JSON body against the 'Item' class schema
    return item

• The Solution: Pydantic Models.
• Instead of writing checks, we write a Blueprint.
• By inheriting from BaseModel, we tell Pydantic: “This is what an Item should look like.”
• Mechanism: When a request comes in, FastAPI checks it against this blueprint.
• If the tags list is missing? No problem, it provides a default [].
• If price comes in as the string “5.50”? Pydantic converts it to a float for you.

Editor Support

The “Invisible” Feature.

Because FastAPI uses standard Python types, your IDE (VS Code, PyCharm) understands the code.

• Scenario: You type item. (dot) inside your function.
• Result: The editor immediately suggests .name, .price, and .tags because it knows item is of type Item.

• Concept: This isn’t just about catching errors; it’s about Developer Experience (DX).
• Because we use standard Python classes, VS Code (the “Client” in our LSP example from M1) can talk to its Language Server and tell you exactly what fields exist.
• You don’t have to memorize the database schema. The editor tells you.

Constraints: Field

Pydantic uses Field or specialized types to define further constraints.

from pydantic import Field

class User(BaseModel):
    # Set: {Strings with length between 3 and 10}
    username: str = Field(min_length=3, max_length=10)

• Refining the Mold: Sometimes, saying “it’s a string” isn’t enough.
• A username is a string, but it’s not any string. It can’t be 1 character, and it can’t be 1 million characters.
• Field() allows us to add metadata constraints.
• This is “Declarative Validation”. We declare the rules, and Pydantic enforces them.

The Annotated

Annotated was introduced (in PEP 593) to allow “tool-specific metadata” to exist alongside types:

from typing import Annotated
from pydantic import BaseModel, Field

class User(BaseModel):
    # The 'int' is the type, the 'Field' is the metadata tag
    age: Annotated[int, Field(gt=18, lt=100)]

• For editors and other tools, the type of age is still the first thing: str.
• For Pydantic, it knows to enforce additional constraints specified by Field.

• Deep Dive: Why Annotated?
• Python is a dynamic language. Static type checkers (like Mypy) look at age: int and stop there. They don’t care about min_length.
• Annotated allows us to serve two masters:
  1. The Type Checker: Sees int. Happy.
  2. FastAPI/Pydantic: Sees Field(gt=18). Enforces logic.
• It’s a way to attach “Runtime Metadata” to “Static Types”.

Using Type Hints

class Fruit(BaseModel):
    # Exclusive OR: either 'red' or 'green'
    color: Literal['red', 'green']

    # Nested Structure
    bazam: dict[str, list[tuple[int, bool, float]]]  

• Advanced Sculpting:
• Literal: Think of this as a “Dropdown Menu” or an “Enum”. If the user sends “blue”, the gate slams shut.
• Nested Structures: This is where Pydantic shines.
• We have a dictionary, where keys are strings, and values are lists of tuples…
• Trying to validate this manually would be a nightmare of nested if/for loops.
• Here? It’s one line.

Custom Parsing Functions

If you wish to customize:

• On failure: raise ValueError
• On success: return

class User(BaseModel):
    # Set: {Integers that are even} (Custom Subset)
    even_id: int

    @field_validator('even_id')
    def must_be_even(cls, v):
        if v % 2 != 0: raise ValueError("Must be even")
        return v

• Power User Limit: Sometimes, declarative rules (min/max) aren’t enough.
• “Must be an even number” is a logical check, not just a range check.
• The Hook: Pydantic lets you escape the declarative world and write raw Python functions when you need to.
• If you raise a ValueError, FastAPI catches it and converts it into a nice generic 422 Unprocessable Entity error for the user.

Key Takeaways

• Blueprints: Use Python classes for automatic validation and parsing.
• DX: Type hints enable auto-completion and catch errors early.
• Constraints: Use Field and Annotated for precise data rules.
• Validation: Use @field_validator for custom business logic.