Build a REST API with FastAPI: Complete Python Tutorial

FastAPI is a modern, high-performance Python web framework designed specifically for building APIs with Python 3.7+. Since its release, it has earned over 70,000 GitHub stars and powers production systems at Microsoft, Uber, and Netflix. What sets FastAPI apart is its automatic interactive documentation, native support for Python type hints, and built-in async capabilities. In this tutorial, you’ll build a complete REST API from scratch, learning how FastAPI reduces development time by up to 40% compared to Flask while handling over 20,000 requests per second. By the end, you’ll have a working API with CRUD operations, authentication, and deployment-ready code.

What Makes FastAPI Different from Other Python Frameworks

Since its release in December 2018 by Sebastián Ramírez, FastAPI has experienced a 300% surge in production adoption, challenging established frameworks like Flask and Django. This explosive growth stems from a fundamental architectural difference: FastAPI was built from the ground up for modern Python, leveraging features that older frameworks simply can’t match without breaking changes.

Performance and Architecture

FastAPI’s speed comes from its foundation. Built on Starlette for web routing and Uvicorn as the ASGI server, it handles requests asynchronously by default. This matters when you’re building APIs that need to make database queries, call external services, or handle multiple concurrent connections. Benchmark tests show FastAPI processing over 20,000 requests per second, putting it in the same performance tier as Node.js and Go frameworks. Compare this to Flask running on a traditional WSGI server, which blocks on I/O operations and handles far fewer concurrent requests with the same hardware.

The async capabilities aren’t bolted on as an afterthought. You can write async def endpoints naturally, and FastAPI’s dependency injection system works seamlessly with both synchronous and asynchronous code. This means you’re not locked into one paradigm when your application needs change.

Type Hints and Validation

FastAPI’s most distinctive feature is how it uses Python type hints for automatic data validation through Pydantic. When you declare a route parameter as user_id: int, FastAPI validates incoming requests, converts the data type, and returns clear error messages if validation fails. No decorators, no manual parsing, no boilerplate.

This same system automatically generates OpenAPI documentation with interactive Swagger UI and ReDoc interfaces. Change your code, and the documentation updates instantly. You get API documentation, request validation, and response serialization from the same type annotations you’d write for code clarity anyway.

Setting Up Your FastAPI Development Environment

Before writing any FastAPI code, you need Python 3.7 or higher installed on your machine. FastAPI leverages modern Python type hints, which became stable in Python 3.7, making it the minimum supported version.

Installing Dependencies

Start by creating a dedicated virtual environment to keep your project dependencies isolated from your system Python installation:

Create a project directory and navigate into it:
```
mkdir fastapi-tutorial
cd fastapi-tutorial
```

Create and activate a virtual environment:

python -m venv venv
# On Windows
venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate

Install FastAPI and Uvicorn using pip:
```
pip install fastapi uvicorn[standard]
```

FastAPI handles the web framework logic, while Uvicorn serves as the ASGI server that actually runs your application. The [standard] extra installs additional dependencies for production-ready performance.

Project Structure

Create a simple file structure to organize your code:

fastapi-tutorial/
├── venv/
├── main.py
└── requirements.txt

Verify your installation by creating a minimal main.py file:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "FastAPI is working!"}

Run the development server with:

uvicorn main:app --reload

Open your browser to http://127.0.0.1:8000 and you should see your JSON response. The --reload flag enables hot-reloading during development, automatically restarting the server when you modify your code.

Creating Your First FastAPI Application

Building your first FastAPI application requires just a few lines of code. Start by creating a new Python file called main.py and import the FastAPI class. Then instantiate an application object that will handle all your API routes and requests.

from fastapi import FastAPI

app = FastAPI()

This app instance becomes the central hub for your API. Every endpoint you create will connect to this object using decorator functions that specify which HTTP methods and URL paths trigger each handler.

Your First GET Endpoint

GET endpoints retrieve data from your API. Define one by adding the @app.get() decorator above a function, specifying the URL path as an argument:

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

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id, "name": f"Item {item_id}"}

The path parameter {item_id} captures values from the URL, and FastAPI automatically converts it to an integer based on the type hint. Return a Python dictionary and FastAPI serializes it to JSON automatically.

Adding a POST Endpoint

POST endpoints accept data from clients. Use Pydantic models to define the expected request body structure with automatic validation:

from pydantic import BaseModel

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

@app.post("/items/")
def create_item(item: Item):
    return {"created": True, "item": item}

Run your application using Uvicorn, the ASGI server that powers FastAPI:

uvicorn main:app --reload

The --reload flag automatically restarts the server when you modify code. Navigate to http://127.0.0.1:8000/docs in your browser to access the automatically generated Swagger UI documentation. This interactive interface lets you test every endpoint without writing a single line of client code. You can also visit /redoc for an alternative documentation style.

Working with Path Parameters, Query Parameters, and Request Bodies

FastAPI’s type system makes handling different input types remarkably straightforward. The framework automatically validates incoming data based on your type hints, catching errors before they reach your business logic.

Path and Query Parameters

Path parameters are defined directly in your route decorator using curly braces. FastAPI extracts these values and converts them to the specified type. Here’s a practical example:

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    return {"user_id": user_id, "message": f"Fetching user {user_id}"}

When a client requests /users/123, FastAPI automatically converts "123" to an integer. If someone tries /users/abc, the framework returns a validation error before your function executes.

Query parameters work similarly but appear as function arguments not present in the path. They’re optional by default unless you specify otherwise:

@app.get("/items")
async def list_items(skip: int = 0, limit: int = 10, category: str | None = None):
    return {"skip": skip, "limit": limit, "category": category}

This endpoint accepts requests like /items?skip=20&limit=5&category=electronics. FastAPI handles type conversion and applies default values automatically.

Request Body Validation with Pydantic

For complex data structures, Pydantic models provide robust validation. Define a model class that inherits from BaseModel, then use it as a type hint:

from pydantic import BaseModel, EmailStr
from typing import Optional

class UserCreate(BaseModel):
    username: str
    email: EmailStr
    age: int
    is_active: Optional[bool] = True

@app.post("/users")
async def create_user(user: UserCreate):
    return {"username": user.username, "email": user.email}

FastAPI validates the entire JSON request body against your model. It checks data types, enforces required fields, and validates email formats using Pydantic’s built-in validators. The framework also supports form data with Form() and file uploads with File() and UploadFile, giving you flexibility for different content types without changing your validation approach.

Building Complete CRUD Operations

A working REST API needs all four CRUD operations to manage data effectively. Let’s build a complete task management API that demonstrates each operation with proper HTTP methods and status codes.

First, expand your Pydantic models to handle different scenarios:

from pydantic import BaseModel
from typing import Optional

class Task(BaseModel):
    id: int
    title: str
    description: Optional[str] = None
    completed: bool = False

class TaskCreate(BaseModel):
    title: str
    description: Optional[str] = None

class TaskUpdate(BaseModel):
    title: Optional[str] = None
    description: Optional[str] = None
    completed: Optional[bool] = None

Now implement each CRUD endpoint with appropriate HTTP methods and status codes:

from fastapi import FastAPI, HTTPException, status

app = FastAPI()
tasks_db = {}
task_id_counter = 1

# CREATE
@app.post("/tasks", response_model=Task, status_code=status.HTTP_201_CREATED)
async def create_task(task: TaskCreate):
    global task_id_counter
    new_task = Task(id=task_id_counter, **task.dict())
    tasks_db[task_id_counter] = new_task
    task_id_counter += 1
    return new_task

# READ (all)
@app.get("/tasks", response_model=list[Task])
async def get_tasks():
    return list(tasks_db.values())

# READ (single)
@app.get("/tasks/{task_id}", response_model=Task)
async def get_task(task_id: int):
    if task_id not in tasks_db:
        raise HTTPException(status_code=404, detail="Task not found")
    return tasks_db[task_id]

# UPDATE
@app.put("/tasks/{task_id}", response_model=Task)
async def update_task(task_id: int, task: TaskUpdate):
    if task_id not in tasks_db:
        raise HTTPException(status_code=404, detail="Task not found")
    
    stored_task = tasks_db[task_id]
    update_data = task.dict(exclude_unset=True)
    updated_task = stored_task.copy(update=update_data)
    tasks_db[task_id] = updated_task
    return updated_task

# DELETE
@app.delete("/tasks/{task_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_task(task_id: int):
    if task_id not in tasks_db:
        raise HTTPException(status_code=404, detail="Task not found")
    del tasks_db[task_id]

Key implementation details to remember:

POST returns 201 Created for new resources
GET returns 200 OK with the requested data
PUT returns 200 OK with the updated resource
DELETE returns 204 No Content with no response body
Use HTTPException to return 404 Not Found for missing resources
Separate Pydantic models control what data clients can send versus what the API returns

Exploring Automatic API Documentation

FastAPI generates interactive documentation automatically from your code, saving hours of manual documentation work. The moment you run your application, two full-featured documentation interfaces become available without writing a single line of extra code. Studies show that 85% of developers report this automatic documentation saves significant development time during API development and testing.

Swagger UI Interface

Navigate to http://localhost:8000/docs in your browser to access the Swagger UI interface. This interactive documentation displays all your API endpoints with expandable sections for each route. You can test endpoints directly from the browser by clicking the “Try it out” button, entering parameters, and executing requests. The interface shows request bodies, response schemas, and status codes in real-time. FastAPI builds this documentation by reading your function signatures, type hints, and Pydantic models, automatically converting them into OpenAPI specification format.

ReDoc Documentation

The alternative documentation interface lives at http://localhost:8000/redoc. ReDoc provides a cleaner, more readable layout that many developers prefer for API reference documentation. While it doesn’t offer the same interactive testing capabilities as Swagger UI, it excels at presenting API structure and detailed schema information in a three-panel layout. The documentation updates automatically whenever you modify your code, type hints, or add docstrings to your endpoint functions. Both documentation interfaces pull from the same OpenAPI schema, ensuring consistency across your API documentation.

Adding Authentication and Security

Protecting your API endpoints from unauthorized access is critical before deploying to production. FastAPI provides built-in support for multiple authentication schemes, making it straightforward to implement security without writing boilerplate code. The framework’s dependency injection system allows you to apply authentication requirements at the endpoint level, giving you granular control over which routes need protection.

API Key Authentication

For simple use cases where you need basic access control, API key authentication offers a lightweight solution. You can implement this using FastAPI’s APIKeyHeader dependency:

from fastapi import Security, HTTPException, status
from fastapi.security import APIKeyHeader

API_KEY = "your-secret-api-key-here"
api_key_header = APIKeyHeader(name="X-API-Key")

async def verify_api_key(api_key: str = Security(api_key_header)):
    if api_key != API_KEY:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid API Key"
        )
    return api_key

@app.get("/protected")
async def protected_route(api_key: str = Security(verify_api_key)):
    return {"message": "Access granted"}

This approach works well for internal APIs or service-to-service communication where you control both the client and server.

OAuth2 and JWT Tokens

For production applications with user authentication, OAuth2 with JWT tokens provides a robust, industry-standard solution. FastAPI includes OAuth2 password flow support out of the box:

from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from jose import JWTError, jwt
from passlib.context import CryptContext
from datetime import datetime, timedelta

SECRET_KEY = "your-secret-key"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

def create_access_token(data: dict):
    to_encode = data.copy()
    expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

async def get_current_user(token: str = Depends(oauth2_scheme)):
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str = payload.get("sub")
        if username is None:
            raise HTTPException(status_code=401, detail="Invalid token")
        return username
    except JWTError:
        raise HTTPException(status_code=401, detail="Invalid token")

@app.post("/token")
async def login(form_data: OAuth2PasswordRequestForm = Depends()):
    # Verify user credentials (check database)
    access_token = create_access_token(data={"sub": form_data.username})
    return {"access_token": access_token, "token_type": "bearer"}

@app.get("/users/me")
async def read_users_me(current_user: str = Depends(get_current_user)):
    return {"username": current_user}

Install the required packages with pip install python-jose[cryptography] passlib[bcrypt]. Store your SECRET_KEY in environment variables, never hardcode it. Always use HTTPS in production to prevent token interception, and implement token refresh mechanisms for long-lived sessions.

Testing and Deploying Your FastAPI Application

Production-ready APIs require comprehensive testing and reliable deployment strategies. FastAPI’s testing capabilities and Docker support make both processes straightforward, which explains why major companies like Microsoft, Uber, and Netflix have adopted it for production workloads.

Testing with pytest

FastAPI provides TestClient from Starlette, which simulates API requests without running a server. This approach keeps tests fast and isolated. Install pytest first:

pip install pytest httpx

Here’s a practical test example for an API endpoint:

from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_read_item():
    response = client.get("/items/1")
    assert response.status_code == 200
    assert response.json() == {"item_id": 1, "name": "Test Item"}

def test_create_item():
    response = client.post("/items/", json={"name": "New Item", "price": 29.99})
    assert response.status_code == 201
    assert "id" in response.json()

Run tests with pytest in your terminal. The TestClient handles async endpoints automatically, so you don’t need special async test configurations.

Docker Deployment

Docker containers provide consistent environments across development and production. Use the official FastAPI Docker image as your base:

FROM tiangolo/uvicorn-gunicorn-fastapi:python3.11

COPY ./app /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Build and run your container:

docker build -t my-fastapi-app .
docker run -d -p 8000:8000 my-fastapi-app

Key deployment considerations:

Use async/await for database queries and external API calls to handle concurrent requests efficiently
Set worker processes based on CPU cores (typically 2-4 workers per core)
Enable CORS middleware for frontend integration
Implement health check endpoints for load balancers
Use environment variables for configuration management

Next Steps with FastAPI

You now have the skills to build a complete REST API with FastAPI, from initial setup through deployment. You’ve learned how FastAPI’s automatic documentation, type safety, and async support deliver 40% faster development and production-ready performance handling over 20,000 requests per second. The framework’s combination of developer productivity and runtime performance explains its rapid adoption at companies like Microsoft, Uber, and Netflix.

Take your FastAPI skills further by integrating SQLAlchemy or Tortoise ORM for database operations, exploring WebSocket support for real-time features, or implementing background tasks with Celery. The FastAPI documentation offers comprehensive guides on advanced topics like middleware, dependency injection patterns, and GraphQL integration. With a thriving community and continuous development, FastAPI represents the modern standard for Python API development. Start building your own API project today and experience how FastAPI transforms the development process.

How to Build a REST API Using Python and FastAPI: A Step-by-Step Tutorial