Fastapi Tutorial: Building Restful Apis With Python

Building production-ready RESTful APIs in Python requires balancing developer velocity, automatic validation, and asynchronous performance. FastAPI delivers all three by combining modern Python type hints with Starlette and Pydantic. If you want to build high-performance web services without drowning in boilerplate code or manual documentation upkeep, FastAPI stands as the premier framework choice.

This guide walks you through setting up a project, structuring robust routes, handling data validation with Pydantic, connecting databases, and deploying your service with confidence.

Setting Up Your FastAPI Development Environment

To start building, you need Python installed on your machine alongside a virtual environment manager. FastAPI itself doesn't include an ASGI server, so you must install Uvicorn to run your code.

Open your terminal and run the following commands to initialize your project:

mkdir fastapi-demo
cd fastapi-demo
python -m venv venv
source venv/bin/activate
pip install fastapi uvicorn pydantic

Create a file named main.py in your project root directory. Write a minimal application to verify your setup:

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"message": "Welcome to FastAPI"}

Launch the development server by executing uvicorn main:app --reload. The --reload flag instructs the server to restart automatically whenever you modify your source files. Open your browser and navigate to [http://127.0.0.1:8000](http://127.0.0.1:8000) to see your JSON response. FastAPI also auto-generates interactive API documentation at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) powered by Swagger UI, and an alternative documentation interface at [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc).

Defining Data Models with Pydantic

Data validation is often the most tedious part of backend development. FastAPI leverages Pydantic models to handle incoming request payloads, validate data types, and serialize responses automatically.

When a client sends malformed JSON to your endpoint, FastAPI intercepts the request and returns a detailed 422 Unprocessable Entity error highlighting the exact field that failed validation.

Create a schema for a resource, such as a product item in an e-commerce catalog:

from typing import Optional
from pydantic import BaseModel, Field


class Item(BaseModel):
    name: str = Field(..., min_length=2, max_length=50)
    description: Optional[str] = None
    price: float = Field(..., gt=0, description="The price must be greater than zero")
    tax: Optional[float] = None

By specifying standard Python types alongside Field constraints, you eliminate manual type casting and regex checking. If a client submits a string instead of a float for the price field, Pydantic catches it immediately before your business logic ever runs.

Implementing CRUD Operations

A true RESTful API implements standard HTTP methods mapping directly to Create, Read, Update, and Delete operations. Let's build a complete in-memory resource manager for inventory items.

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    price: float
    in_stock: bool = True


# In-memory database simulation
inventory = {}
counter = 0


@app.post("/items/", status_code=status.HTTP_201_CREATED)
def create_item(item: Item):
    global counter
    counter += 1
    inventory[counter] = item.dict()
    return {"item_id": counter, **inventory[counter]}


@app.get("/items/")
def list_items(skip: int = 0, limit: int = 10):
    items_list = list(inventory.items())
    return [{"item_id": k, **v} for k, v in items_list[skip : skip + limit]]


@app.get("/items/{item_id}")
def get_item(item_id: int):
    if item_id not in inventory:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND, detail="Item not found"
        )
    return {"item_id": item_id, **inventory[item_id]}


@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item):
    if item_id not in inventory:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND, detail="Item not found"
        )
    inventory[item_id] = item.dict()
    return {"item_id": item_id, **inventory[item_id]}


@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_item(item_id: int):
    if item_id not in inventory:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND, detail="Item not found"
        )
    del inventory[item_id]
    return None

This implementation demonstrates proper status code management. Successful creation returns a 201 Created status, deletions return 204 No Content, and missing records return a clean 404 Not Found response via FastAPI's HTTPException.

Handling Query Parameters and Path Validation

FastAPI differentiates between path parameters (parts of the URL path) and query parameters (parameters appended after the question mark in the URL) simply by checking their type declarations.

You can enforce rigorous validation rules on query parameters using the Query class:

from typing import Optional
from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/search/")
def search_inventory(
    q: Optional[str] = Query(
        None, min_length=3, max_length=50, description="Search keyword"
    ),
    page: int = Query(1, ge=1, description="Page number"),
    per_page: int = Query(20, ge=1, le=100, description="Items per page"),
):
    return {
        "query": q,
        "page": page,
        "per_page": per_page,
        "results": [],
    }

If a client requests /search/?page=0, FastAPI rejects the request instantly because ge=1 enforces a minimum value of 1. This keeps invalid pagination parameters from reaching your database queries.

Managing Dependencies with Depends

As your application grows, you will need shared logic across multiple endpoints, such as database sessions, rate limiting, or authentication checks. FastAPI provides a powerful Dependency Injection system via the Depends class.

Dependencies are regular functions or classes that share the same signature as path operation functions. Here is how you can implement a simple token-based verification dependency:

from fastapi import Depends, FastAPI, Header, HTTPException, status

app = FastAPI(title="Secure API")


async def verify_token(x_token: str = Header(...)):
    if x_token != "secret-api-token":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid or missing API token",
        )
    return x_token


@app.get("/protected-data/")
def get_protected_data(token: str = Depends(verify_token)):
    return {"message": "Access granted", "token_used": token}

When a request arrives at /protected-data/, FastAPI executes verify_token first, extracting the X-Token header. If validation passes, the token value is injected into the path operation function. If it fails, execution halts and returns a 401 Unauthorized response immediately.

For production database setups, you can follow the SQLAlchemy Documentation to create session generators and inject them via Depends to handle connection lifecycles cleanly.

Common Mistakes to Avoid

Building scalable web applications requires steering clear of architectural traps that degrade performance or invite security vulnerabilities.

• Blocking the Event Loop: Avoid running synchronous, blocking operations (like heavy file I/O or time-consuming CPU-bound computations) directly inside async def route handlers. If you must use blocking libraries, declare your path operation with standard def instead of async def so FastAPI runs it in an external thread pool.
• Ignoring Input Validation: Never accept raw dictionaries or untrusted data blobs by bypassing Pydantic. Relying on dynamic parsing without schemas defeats FastAPI's primary safety and documentation advantages.
• Hardcoding Configuration: Avoid hardcoding database URLs, secret keys, or environment settings directly in source files. Use Pydantic's BaseSettings or standard environment variables to manage configuration securely.
• Overlooking Exception Handlers: Don't let unhandled internal server errors leak stack traces to clients. Register custom exception handlers using @app.exception_handler to return clean, standardized error payloads.

Frequently Asked Questions

Is FastAPI faster than Flask and Django?

Yes. FastAPI is built on top of Starlette for web handling and Pydantic for data parsing, making it one of the fastest Python frameworks available, rivaling NodeJS and Go implementations in performance benchmarks.

Should I use def or async def for my FastAPI routes?

Use def if your code performs blocking synchronous operations (such as standard database drivers like Psycopg2). Use async def if your code leverages asynchronous libraries (such as HTTPX, Motor, or databases supporting async drivers like asyncpg).

How does FastAPI generate interactive documentation?

FastAPI automatically reads standard Python type hints, Pydantic models, and docstrings to generate an OpenAPI specification schema, which powers the built-in Swagger UI and ReDoc endpoints out of the box.

Can FastAPI handle background tasks?

Yes. FastAPI includes a built-in BackgroundTasks utility that allows you to run tasks (such as sending confirmation emails or processing logs) after returning a response to the client.

How do I deploy FastAPI to production?

You deploy FastAPI applications using an ASGI server like Uvicorn managed by a process manager such as Systemd, or containerized via Docker behind a reverse proxy like Nginx. You can consult the Python Packaging Authority for standard packaging and containerization guidelines.