fastapi-todo-app

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

fastapi-todo-app

★ 14 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Todo API

A production-ready REST API for managing a todo list, built with **FastAPI** and **PostgreSQL**.

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)]()
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115%2B-009688)]()

---

## Features

- Full CRUD — create, read, update, and delete todos
- Auto-generated interactive docs (Swagger UI + ReDoc)
- Pydantic v2 validation for all request/response payloads
- PostgreSQL persistence via SQLAlchemy 2.0 ORM
- Database migrations-ready (Alembic compatible)
- One-command startup with Docker Compose
- Health-checked service dependencies

---

## System Architecture

```mermaid
flowchart TD
    Client[Client / Browser] -->|HTTP| FastAPI[FastAPI App]

subgraph FastAPI [FastAPI Application]
        Router[Router: /todos]
        Schema[Pydantic Schemas<br/>TodoCreate / TodoUpdate / TodoResponse]
        CRUD[CRUD Operations]
        DB_Dep[get_db Dependency<br/>yields Session per request]
    end

FastAPI --> SQLAlchemy[SQLAlchemy ORM]
    SQLAlchemy --> PG[(PostgreSQL)]

subgraph PG [PostgreSQL Database]
        Todos[(todos table)]
    end
```

**Request flow:**
1. Client sends HTTP request to FastAPI
2. Router matches the path and calls the endpoint handler
3. Pydantic schema validates the request body (if any)
4. The `get_db` dependency injects a SQLAlchemy `Session`
5. CRUD logic runs the query through the session
6. SQLAlchemy translates to SQL and executes against PostgreSQL
7. Response is serialized via the Pydantic response schema

---

## Tech Stack

| Layer | Technology |
|---|---|
| Framework | [FastAPI](https://fastapi.tiangolo.com/) |
| ORM | [SQLAlchemy 2.0](https://www.sqlalchemy.org/) |
| Validation | [Pydantic v2](https://docs.pydantic.dev/) |
| Database | [PostgreSQL](https://www.postgresql.org/) 16+ |
| ASGI Server | [Uvicorn](https://www.uvicorn.org/) |
| Containerization | Docker & Docker Compose |

---

## Quick Start (Docker)

```bash
# Clone the repository
git clone <repo-url> && cd todo-app

# Start everything
docker compose up --build
```

The API is now available at `http://localhost:8000`.

---

## Local Development

### Prerequisites

- Python 3.10+
- PostgreSQL 16+ running locally

### Setup

```bash
# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure database URL
cp .env.example .env
# Edit .env with your PostgreSQL credentials

# Start the dev server
uvicorn app.main:app --reload
```

---

## API Reference

Base URL: `http://localhost:8000`

Interactive docs: `http://localhost:8000/docs` (Swagger) or `http://localhost:8000/redoc` (ReDoc)

### `GET /todos`

List all todos, ordered by creation date (newest first).

**Response `200`:**

```json
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "title": "Buy groceries",
    "description": "Milk, eggs, bread",
    "completed": false,
    "created_at": "2025-01-01T12:00:00",
    "updated_at": "2025-01-01T12:00:00"
  }
]
```

### `GET /todos/{id}`

Get a single todo by UUID.

**Response `200`:** Single todo object.

**Response `404`:** `{"detail": "Todo not found"}`

### `POST /todos`

Create a new todo.

**Request body:**

```json
{
  "title": "Buy groceries",
  "description": "Milk, eggs, bread"
}
```

**Response `201`:** The created todo object with generated `id` and timestamps.

### `PUT /todos/{id}`

Update an existing todo. All fields are optional — only provided fields are updated.

**Request body:**

```json
{
  "title": "Buy organic groceries",
  "completed": true
}
```

**Response `200`:** The updated todo object.

**Response `404`:** `{"detail": "Todo not found"}`

### `DELETE /todos/{id}`

Delete a todo.

**Response `204`:** No content.

**Response `404`:** `{"detail": "Todo not found"}`

---

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `DATABASE_URL` | `postgresql://postgres:postgres@localhost:5432/todos` | PostgreSQL connection string |

---

## Project Structure

```
todo-app/
├── app/
│   ├── __init__.py
│   ├── config.py              # Settings from environment
│   ├── database.py            # Engine, session, Base, get_db dependency
│   ├── models.py              # SQLAlchemy Todo model
│   ├── schemas.py             # Pydantic request/response models
│   ├── main.py                # FastAPI application entrypoint
│   └── routers/
│       ├── __init__.py
│       └── todos.py           # CRUD route handlers
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .env.example
└── README.md
```

---

## Database Migrations (Alembic)

While tables are auto-created on startup for development, production deployments should use Alembic:

```bash
# Install Alembic
pip install alembic

# Initialize
alembic init alembic

# Configure alembic.ini with DATABASE_URL, then:
alembic revision --autogenerate -m "initial"
alembic upgrade head
```

After that, remove or disable `Base.metadata.create_all()` in `app/main.py` so migrations are the sole source of truth.

---

## Deployment

### Gunicorn with Uvicorn workers

```bash
pip install gunicorn
gunicorn app.main:app \
  --worker-class uvicorn.workers.UvicornWorker \
  --workers 4 \
  --bind 0.0.0.0:8000
```

### Environment

Set `DATABASE_URL` to point to your production PostgreSQL instance (use a strong password and consider connection pooling like PgBouncer for high traffic).

---

## License

MIT

fastapi-todo-app

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README