How to Build REST API with Python And FastAPI

Build REST API with Python And FastAPI is easy to demonstrate and surprisingly easy to get wrong.

A few lines of Python can return JSON from an endpoint. But a useful API needs more than a successful GET request. It needs a clear resource model, validated input, predictable errors, safe response data, testable boundaries, and a deployment plan that does not collapse when the first real dependency becomes slow.

In this tutorial, you will build a small but thoughtfully structured REST API with Python and FastAPI. We will start with a working endpoint, then add typed Pydantic models, CRUD operations, pagination, dependency injection, error handling, OpenAPI documentation, and automated tests. Along the way, we will also examine the parts that many FastAPI tutorials skip: why async def does not automatically make blocking code non-blocking, why an object ID is not authorization, and why an in-memory example must never be confused with a production database.

If you are new to API design, you may want to begin with Vertex Frontier’s guide to what an API is and how APIs work. If you already understand HTTP and JSON, you can start building immediately. By the end, you will have a runnable project and a clear, honest checklist for turning that learning project into a real service.

What is FastAPI, and how is it different from a REST API?

A REST API is an HTTP interface designed around resources, representations, stateless requests, standard methods, and meaningful status codes. For example, /api/v1/tasks/42 represents one task, while GET reads it, PATCH changes selected fields, and DELETE removes it.

FastAPI is the Python framework used to implement that interface. Its documented features include typed path and query parameters, Pydantic-based request validation, dependency injection, automatic OpenAPI schema generation, and interactive documentation. The official FastAPI first-steps guide demonstrates the smallest version of this flow.

That distinction matters. FastAPI does not decide whether your API has sensible resource names, correct authorization, safe database transactions, useful logs, or a rollback plan. The framework gives you building blocks. Your application design determines whether those blocks form a reliable service.

If the HTTP concepts are new, start with Vertex Frontier’s guide to what an API is and how APIs work before continuing. This article assumes you understand the basic idea of a client sending a request and receiving a response.

The project we will build

We will use a task resource because it demonstrates the important mechanics without requiring an elaborate business domain.

The API contract comes before the code. A route is easier to implement and test when its input, output, and failure behavior are already explicit.

Before and after: the difference between a demo route and an API you can maintain

A common tutorial starts with one file and one dictionary. That is useful for learning the request cycle, but it hides the decisions that become painful later.

The unusual but important insight is this: the most valuable production lesson in a beginner API tutorial may be learning where the tutorial stops. A bounded demo is honest and useful. A toy service described as secure, durable, or scalable is not.

Step 1: Create an isolated Python project

Use a virtual environment or a lock-file-based workflow. Python’s official venv documentation describes virtual environments as disposable environments that should be recreated from project dependencies rather than committed to version control.

This article uses uv as the primary workflow because it can resolve and lock the environment. If your team standardizes on venv and pip, use that consistently instead; do not mix several package managers in one copy-paste path.

Bash — create and run the project:

mkdir fastapi-tasks
cd fastapi-tasks
uv init
uv add "fastapi[standard]==0.141.1" "pytest" "httpx"
uv lock
uv run fastapi dev app/main.py

The exact resolved versions should be recorded in your lock file. FastAPI’s official versioning guidance and release documentation are more important than a vague instruction to install “the latest” package. FastAPI is still in the 0.x series, so a minor release can require compatibility checks.

Version and compatibility matrix

Use this table as a publication gate, not as a promise that every future release will behave identically. The versions below are the reviewed baseline for this article; re-run the clean-install and test commands when you update them.

If you do not use uv, the portable fallback is:

Bash — venv and pip fallback:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "fastapi[standard]==0.141.1" pytest httpx
python -m uvicorn app.main:app --relo

On Windows, activate the environment with .venv\Scripts\activate. The important practice is not the shell command itself. It is that the command, dependency file, and tested versions agree.

Step 2: Build the smallest working endpoint

Create the initial package structure:

Project structure:

fastapi-tasks/
├── app/
│   ├── __init__.py
│   └── main.py
├── tests/
│   └── test_tasks.py
├── pyproject.toml
├── uv.lock
└── .gitignore

Start with a route and let FastAPI show you what it adds:

Python — app/main.py:

from fastapi import FastAPI
app = FastAPI(
title="Task API",
version="0.1.0",
description="A small REST API built with Python and FastAPI",
)
@app.get("/health", tags=["system"])
def health() -> dict[str, str]:
return {"status": "ok"}

Open http://127.0.0.1:8000/health in a browser or API client. Then inspect:

• /docs for Swagger UI.
• /redoc for ReDoc.
• /openapi.json for the generated schema.

The schema is not just decoration. It is a machine-readable description that can feed client generation, contract review, and integration discussions. It is also an inventory of what your service exposes, so review it before deployment.

A strong FastAPI workflow uses the generated documentation as a feedback loop. If the OpenAPI schema is confusing, the API contract or model design probably needs work.

Step 3: Model input and output with Pydantic

Unstructured dictionaries make it easy to accept accidental fields, return inconsistent shapes, or forget constraints. Pydantic models turn the request and response boundary into explicit Python types and JSON Schema.

The Pydantic models documentation covers validation and serialization. In current Pydantic v2 code, use methods such as model_dump() rather than presenting Pydantic v1 methods as the default.

Create separate models for creation, partial updates, and responses:

Python — app/schemas.py:

from datetime import datetime
from pydantic import BaseModel, Field
class TaskCreate(BaseModel):
title: str = Field(min_length=1, max_length=200)
description: str | None = Field(default=None, max_length=2000)
class TaskUpdate(BaseModel):
title: str | None = Field(default=None, min_length=1, max_length=200)
description: str | None = Field(default=None, max_length=2000)
completed: bool | None = None
class TaskRead(BaseModel):
id: int
title: str
description: str | None
completed: bool
created_at: datetime

Why separate models?

• TaskCreate describes what a client may send when creating a task.
• TaskUpdate describes a partial change; omitted fields stay unchanged.
• TaskRead describes what the API promises to return.

That last distinction is a security boundary. If an internal object later contains a password hash, billing flag, or private note, a response model can prevent fields outside the public contract from being serialized. FastAPI documents response-model filtering as security-relevant, but it does not replace authorization or careful data handling.

A field declared as str | None is not necessarily optional unless it also has a default. Test the missing-field behavior instead of relying on intuition. Also remember that validation and coercion are not identical: a library may convert compatible input, while strict validation rejects it. Choose and document the behavior your API needs.

Step 4: Move storage behind a small repository

The in-memory repository below is deliberately simple. It exists to isolate HTTP behavior from storage behavior. It does not pretend to be a database.

Python — app/repository.py:

from datetime import UTC, datetime
from .schemas import TaskCreate, TaskRead, TaskUpdate
class TaskRepository:
def init(self) -> None:
self._tasks: dict[int, TaskRead] = {}
self._next_id = 1

def list(self, skip: int = 0, limit: int = 20) -> list[TaskRead]:
    tasks = list(self._tasks.values())
    return tasks[skip : skip + limit]

def get(self, task_id: int) -> TaskRead | None:
    return self._tasks.get(task_id)

def create(self, payload: TaskCreate) -> TaskRead:
    task = TaskRead(
        id=self._next_id,
        title=payload.title,
        description=payload.description,
        completed=False,
        created_at=datetime.now(UTC),
    )
    self._tasks[task.id] = task
    self._next_id += 1
    return task

def update(self, task_id: int, payload: TaskUpdate) -> TaskRead | None:
    current = self._tasks.get(task_id)
    if current is None:
        return None

    changes = payload.model_dump(exclude_unset=True)
    updated = current.model_copy(update=changes)
    self._tasks[task_id] = updated
    return updated

def delete(self, task_id: int) -> bool:
    return self._tasks.pop(task_id, None) is not None

This is a teaching repository, not a concurrency strategy. It resets when the process restarts. Multiple workers would have separate memory. A second process would not see the first process’s tasks. There are no transactions, indexes, backups, migrations, or durability guarantees.

For a persistent service, the next layer is usually a database session and a migration workflow. SQLAlchemy’s APIs are version-sensitive, and Alembic’s autogenerate feature creates candidate migrations that require manual review; it cannot reliably infer every rename or semantic data change. Vertex Frontier’s practical ORM guide is a useful companion when you move from this repository to a relational persistence layer.

Step 5: Add routes, validation, and dependency injection

FastAPI dependencies are reusable callables declared with Depends. They can supply configuration, database sessions, authentication context, or repository objects. The official dependency-injection guide explains the mechanism and its relationship to validation and OpenAPI.

Python — app/dependencies.py:

from typing import Annotated
from fastapi import Depends
from .repository import TaskRepository
_repository = TaskRepository()
def get_repository() -> TaskRepository:
return _repository
Repository = Annotated[TaskRepository, Depends(get_repository)]

Now define the task router. The route layer handles HTTP concerns. The repository handles storage operations.

Python — app/routes.py:

from typing import Annotated
from fastapi import APIRouter, HTTPException, Query, status
from .dependencies import Repository
from .schemas import TaskCreate, TaskRead, TaskUpdate
router = APIRouter(prefix="/api/v1/tasks", tags=["tasks"])
@router.get("", response_model=list[TaskRead])
def list_tasks(
repository: Repository,
skip: Annotated[int, Query(ge=0)] = 0,
limit: Annotated[int, Query(gt=0, le=100)] = 20,
) -> list[TaskRead]:
return repository.list(skip=skip, limit=limit)
@router.post("", response_model=TaskRead, status_code=status.HTTP_201_CREATED)
def create_task(
payload: TaskCreate,
repository: Repository,
) -> TaskRead:
return repository.create(payload)
@router.get("/{task_id}", response_model=TaskRead)
def get_task(task_id: int, repository: Repository) -> TaskRead:
task = repository.get(task_id)
if task is None:
raise HTTPException(status_code=404, detail="Task not found")
return task
@router.patch("/{task_id}", response_model=TaskRead)
def update_task(
task_id: int,
payload: TaskUpdate,
repository: Repository,
) -> TaskRead:
task = repository.update(task_id, payload)
if task is None:
raise HTTPException(status_code=404, detail="Task not found")
return task
@router.delete("/{task_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_task(task_id: int, repository: Repository) -> None:
deleted = repository.delete(task_id)
if not deleted:
raise HTTPException(status_code=404, detail="Task not found")

Finally, connect the router to the application:

Python — app/main.py:

from fastapi import FastAPI
from .routes import router as task_router
app = FastAPI(
title="Task API",
version="0.1.0",
description="A small REST API built with Python and FastAPI",
)
@app.get("/health", tags=["system"])
def health() -> dict[str, str]:
return {"status": "ok"}
app.include_router(task_router)

Request validation and error matrix

This matrix turns implementation details into a client-facing contract. The exact validation payload can vary with the pinned FastAPI and Pydantic versions, so test status codes and stable fields rather than hard-coding every wording detail.

The complete tree is now:

Final learning-project structure:

fastapi-tasks/
├── app/
│   ├── __init__.py
│   ├── dependencies.py
│   ├── main.py
│   ├── repository.py
│   ├── routes.py
│   └── schemas.py
├── tests/
│   └── test_tasks.py
├── pyproject.toml
├── uv.lock
└── .gitignore

This is intentionally smaller than a heavily layered enterprise template. A useful project structure is the smallest structure that makes the next change safer. Adding folders before you have a reason for them creates ceremony, not architecture.

Step 6: Test behavior, not just imports

FastAPI’s testing documentation uses TestClient, which is built on HTTPX and works naturally with pytest for ordinary synchronous test calls. Test the API through its HTTP boundary: status codes, response fields, validation, and failure behavior.

Python — tests/test_tasks.py:

from fastapi.testclient import TestClient
from collections.abc import Iterator
import pytest
from app.main import app
from app.dependencies import get_repository
from app.repository import TaskRepository
@pytest.fixture(autouse=True)
def isolate_repository() -> Iterator[None]:
    """Provide a single fresh repository per test so create-then-read works."""
    repository = TaskRepository()
    app.dependency_overrides[get_repository] = lambda: repository
    yield
    app.dependency_overrides.clear()
@pytest.fixture
def client() -> TestClient:
return TestClient(app)
def test_health_check(client: TestClient) -> None:
response = client.get("/health")
assert response.status_code == 200
assert response.json() == {"status": "ok"}
def test_create_and_read_task(client: TestClient) -> None:
created = client.post(
"/api/v1/tasks",
json={"title": "Write tests", "description": "Cover the happy path"},
)
assert created.status_code == 201
task_id = created.json()["id"]
fetched = client.get(f"/api/v1/tasks/{task_id}")
assert fetched.status_code == 200
assert fetched.json()["title"] == "Write tests"
def test_invalid_task_is_rejected(client: TestClient) -> None:
response = client.post("/api/v1/tasks", json={"title": ""})
assert response.status_code == 422
def test_missing_task_returns_404(client: TestClient) -> None:
response = client.get("/api/v1/tasks/999")
assert response.status_code == 404
assert response.json()["detail"] == "Task not found"
def test_update_and_delete_task(client: TestClient) -> None:
created = client.post("/api/v1/tasks", json={"title": "Temporary"})
task_id = created.json()["id"]
updated = client.patch(
    f"/api/v1/tasks/{task_id}",
    json={"completed": True},
)
assert updated.status_code == 200
assert updated.json()["completed"] is True

deleted = client.delete(f"/api/v1/tasks/{task_id}")
assert deleted.status_code == 204

Run the suite with:

Bash — run tests:

uv run pytest -q

The dependency override gives each test a fresh repository. That is appropriate for this in-memory example. A database-backed test suite needs a more deliberate strategy involving transactions, migrations, fixtures, and cleanup. Do not claim that these tests prove database correctness, multi-worker behavior, or production capacity.

FastAPI troubleshooting matrix

When a small API fails, classify the failure before changing the architecture. This keeps a useful error from turning into a random dependency or worker change.

The async trap: async def is not a performance button

FastAPI supports both async def and normal def path operations. The correct choice depends on the work performed inside the function and the libraries involved. FastAPI’s concurrency guidance explains when awaiting an async library is useful and why blocking libraries need different treatment.

An async def route that calls a blocking function can still block the event loop. A practitioner report in the FastAPI community described an asynchronous endpoint calling a synchronous operation and making unrelated endpoints, including documentation, appear unresponsive while the operation ran. That is useful experience evidence, not a universal benchmark; the exact library, workload, and deployment matter.

Use this decision rule:

Do not infer throughput from a hello-world benchmark. Database pool saturation, worker count, client concurrency, reverse proxies, background jobs, and OS limits can dominate the result. A Reddit load-test report described long waits despite low CPU and memory; that points to a useful diagnostic question, where are requests waiting?, not to a universal pool-size formula.

Common mistakes that make FastAPI APIs fragile

1. Treating CORS as authentication

CORS controls which browser origins may read responses. It does not identify a user, enforce ownership, or protect a server-to-server client. Configure it narrowly for your actual front ends.

2. Using an ID as if it proves authorization

/tasks/42 identifies an object. It does not prove the caller may read or change it. In a real system, the query must be scoped to the authenticated principal or an explicit permission model.

3. Returning internal models directly

Separate public response models from internal objects. Response filtering can reduce accidental exposure, but it cannot repair a data-access rule that fetched the wrong user’s records.

4. Calling a memory dictionary a database

The example resets on restart and diverges across workers. Move to a persistent database and migrations when durability, concurrent access, and recovery matter.

5. Calling every route async def

Async syntax is not a substitute for understanding the I/O behavior of the code inside the route.

6. Testing only the 200 response

An API contract includes invalid input, missing resources, authentication failures, rate limits, and safe error bodies. Test the paths clients actually need to handle.

7. Combining Uvicorn reload and workers

Uvicorn documents --reload as a development feature and makes it mutually exclusive with --workers. Use one development command and a separate deployment command.

8. Letting Alembic generate migrations without review

Autogenerate is a starting point. Review table changes, renames, indexes, constraints, data migrations, and rollback implications before applying a migration.

9. Publishing a debug service

Do not expose stack traces, secrets, SQL statements, tokens, or internal exception details in production responses. Review debug flags, proxy headers, HTTPS termination, and logs as a system.

Authentication, authorization, and the production boundary

A tutorial can demonstrate a protected route, but adding a token parser does not create a complete identity system. FastAPI’s security utilities help extract bearer credentials and integrate security schemes into OpenAPI. Your application still owns token policy, secret management, expiration, rotation, revocation, TLS, and authorization.

JWTs are signed tokens, not encrypted containers. Do not place confidential data in claims merely because the token is signed. Passwords must be hashed with an appropriate password-hashing implementation, never stored in plaintext. A valid token also does not mean the caller can access every object.

Use the OWASP API Security Top 10 as a threat-model checklist. For this small API, the most relevant questions include:

1. Can a caller access another user’s task by changing an ID?
2. Are authentication failures and authorization failures handled distinctly?
3. Are pagination limits, payload sizes, and rate limits appropriate?
4. Does the OpenAPI inventory expose endpoints that should not be public?
5. Are third-party API responses validated before use?
6. Are secrets kept outside source control and logs?

The production boundary is not one final code block. It is a set of operational decisions.

For deployment, Uvicorn’s settings documentation should be checked against your process model. --reload belongs to development. Worker count, replicas, memory, database connections, WebSockets, background jobs, and the reverse proxy must be designed together.

Deployment: what changes after localhost?

A Docker image solves packaging. It does not solve authorization, connection pools, graceful shutdown, observability, or database recovery. A Cloud Run or Kubernetes tutorial solves one provider’s deployment path. It does not make the API provider-independent.

A safe deployment checklist is:

1. Build from a pinned dependency specification.
2. Run the full test suite in CI.
3. Use a production server command without development reload.
4. Configure HTTPS and trusted proxy headers only for proxies you control.
5. Keep secrets in the deployment secret store, not in the repository or logs.
6. Define liveness and readiness separately.
7. Set timeouts, request-size limits, pagination bounds, and rate limits.
8. Measure database wait time and connection-pool usage.
9. Emit structured logs without credentials or sensitive payloads.
10. Add error monitoring and a rollback path.
11. Test migrations and backup restoration before treating the service as durable.
12. Review the generated OpenAPI inventory and public CORS policy.

Verification and rollback plan

Do not treat a green local test run as proof that a deployment is safe. Use a small release gate:

1. Build the exact locked dependency set in a clean environment.
2. Run unit and API tests, then inspect the generated OpenAPI document for unintended routes or fields.
3. Run a smoke test against the deployed health endpoint and one authenticated or representative API operation, where applicable.
4. Observe error rate, latency, database wait time, connection usage, and resource consumption during a controlled release.
5. If a migration or configuration change causes an incident, stop the rollout, preserve logs and request IDs, route traffic back to the last known-good application version, and follow the tested database recovery procedure.
6. Do not “roll back” application code while assuming that a destructive database migration can be reversed automatically. Database rollback must be designed and tested separately.

This is a release protocol, not a benchmark result. The article does not claim that the sample has been deployed or that these steps guarantee zero downtime.

The FastAPI deployment documentation covers process concepts, containers, HTTPS, workers, and deployment environments. Use it as the framework reference, then verify the details for your platform.

A custom endpoint can also sit behind a webhook integration. For example, Vertex Frontier’s guide to connecting Jotform appointments to Zapier explains when a custom webhook endpoint is actually needed. If you build that endpoint with FastAPI, add signature verification, idempotency, replay protection, payload limits, and retry-aware processing; a bare POST route is not enough.

Final checklist

Before exposing this API to users, verify the following in your own environment:

• The clean-install command succeeds from an empty checkout.
• The exact FastAPI, Pydantic, Uvicorn, HTTPX, and pytest versions are recorded.
• /docs, /redoc, and /openapi.json match the intended contract.
• Invalid path, query, and body values return the behavior your clients expect.
• Response models do not expose internal or secret fields.
• Tests do not depend on order or shared in-memory state.
• The chosen async/sync style matches the libraries used by the route.
• A persistent database and reviewed migrations replace the in-memory repository when durability matters.
• Authentication and object-level authorization are designed separately.
• Secrets, HTTPS, CORS, rate limits, timeouts, logs, monitoring, backups, and rollback are addressed.
• The production server command does not combine Uvicorn reload with workers.
• All technical claims and commands are rechecked against the current official documentation.

Conclusion

Building a REST API with Python and FastAPI is straightforward at the syntax level. The harder part is making the boundary between a client and a service explicit: what data enters, what data leaves, what errors mean, which objects a caller may access, and what happens when storage or a dependency is slow.

That is why this tutorial starts with a small in-memory task API but does not end by calling it production-ready. The project gives you a clean path through routing, Pydantic models, CRUD, dependency injection, OpenAPI, and tests. The production checklist tells you where persistence, identity, authorization, observability, and operations begin.

Use the small version to understand the mechanics. Then replace each learning shortcut deliberately—one boundary at a time.

FAQ: FastAPI REST API questions people ask

About The Author

A Gadallh

Ahmed Gadallah is the Founder and Editor of Vertex Frontier, where he publishes research-driven articles on AI, data science, cloud computing, cybersecurity, software engineering, and emerging technologies, with a focus on technical accuracy, clarity, and practical insights.

View all articles by A Gadallh →