Simple Todo API

A simple todo application built with FastAPI and SQLite.

Features

• Create, read, update, and delete todos
• Category management system for organizing todos
• Priority levels for todos (low, medium, high)
• Due date functionality with timezone support
• Comprehensive filtering by category, priority, completion status, due dates, and overdue status
• Search functionality across title and description
• Specialized endpoints for overdue, due soon, and due today todos
• Sorting by due date or creation date
• Subtask management with hierarchical organization
• SQLite database with SQLAlchemy ORM
• Database migrations with Alembic
• FastAPI with automatic OpenAPI documentation
• CORS enabled for all origins
• Health check endpoint

API Endpoints

General

• GET / - Root endpoint with basic information
• GET /health - Health check endpoint
• GET /docs - Interactive API documentation (Swagger UI)
• GET /redoc - Alternative API documentation

Todos

• GET /api/v1/todos - Get all todos (with comprehensive filtering and sorting)
• POST /api/v1/todos - Create a new todo
• GET /api/v1/todos/{todo_id} - Get a specific todo
• PUT /api/v1/todos/{todo_id} - Update a specific todo
• DELETE /api/v1/todos/{todo_id} - Delete a specific todo

Due Date Endpoints

• GET /api/v1/todos/overdue - Get all overdue todos
• GET /api/v1/todos/due-soon - Get todos due within next N days (default 7)
• GET /api/v1/todos/due-today - Get todos due today

Subtasks

• POST /api/v1/todos/{todo_id}/subtasks - Create a subtask for a specific todo
• GET /api/v1/todos/{todo_id}/subtasks - Get all subtasks for a specific todo
• PUT /api/v1/todos/subtasks/{subtask_id}/move - Move a subtask to different parent or make it a main todo

Categories

• GET /api/v1/categories - Get all categories
• POST /api/v1/categories - Create a new category
• GET /api/v1/categories/{category_id} - Get a specific category
• PUT /api/v1/categories/{category_id} - Update a specific category
• DELETE /api/v1/categories/{category_id} - Delete a specific category

Installation

1. Install the dependencies:

pip install -r requirements.txt

2. Run database migrations:

alembic upgrade head

3. Start the application:

uvicorn main:app --reload

The API will be available at http://localhost:8000

Project Structure

├── app/
│   ├── api/
│   │   └── v1/
│   │       ├── __init__.py
│   │       ├── todos.py
│   │       ├── categories.py
│   │       └── projects.py
│   ├── crud/
│   │   ├── __init__.py
│   │   ├── todo.py
│   │   ├── category.py
│   │   └── project.py
│   ├── db/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── session.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── todo.py
│   │   ├── category.py
│   │   ├── project.py
│   │   └── tag.py
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── todo.py
│   │   ├── category.py
│   │   └── project.py
│   ├── utils/
│   │   ├── __init__.py
│   │   └── date_utils.py
│   └── __init__.py
├── alembic/
│   ├── versions/
│   │   ├── 001_initial_todo_table.py
│   │   ├── 002_add_priority_field.py
│   │   ├── 003_add_categories.py
│   │   ├── 004_add_projects.py
│   │   ├── 005_add_tags.py
│   │   ├── 006_add_subtasks.py
│   │   └── 007_add_due_date.py
│   ├── env.py
│   └── script.py.mako
├── alembic.ini
├── main.py
├── requirements.txt
└── README.md

Database

The application uses SQLite database stored at /app/storage/db/db.sqlite. The database schema is managed using Alembic migrations.

Models

Todo Model

Each todo has the following fields:

• id: Unique identifier (auto-generated)
• title: Todo title (required, max 200 characters)
• description: Todo description (optional, max 500 characters)
• completed: Completion status (boolean, default: false)
• priority: Priority level (low, medium, high, default: medium)
• category_id: Reference to category (optional)
• project_id: Reference to project (optional)
• due_date: Due date and time with timezone (optional)
• parent_id: Reference to parent todo for subtasks (optional)
• created_at: Creation timestamp
• updated_at: Last update timestamp

Due Date Features

• is_overdue: Computed property indicating if todo is past due date
• days_until_due: Computed property showing days until due (negative if overdue)
• is_due_soon: Computed property indicating if todo is due within next 7 days
• is_due_today: Computed property indicating if todo is due today

Timezone Support

All due dates are stored with timezone information (UTC). The API accepts ISO 8601 formatted datetime strings and automatically handles timezone conversion.

Category Model

Each category has the following fields:

• id: Unique identifier (auto-generated)
• name: Category name (required, max 100 characters, unique)
• description: Category description (optional, max 500 characters)
• color: Color code in hex format (optional, e.g., #FF0000)
• created_at: Creation timestamp
• updated_at: Last update timestamp

Usage Examples

Creating a Category

curl -X POST "http://localhost:8000/api/v1/categories" \
     -H "Content-Type: application/json" \
     -d '{"name": "Work", "description": "Work related tasks", "color": "#FF6B6B"}'

Creating a Todo with a Category

curl -X POST "http://localhost:8000/api/v1/todos" \
     -H "Content-Type: application/json" \
     -d '{"title": "Review presentation", "description": "Review the quarterly presentation", "category_id": 1, "priority": "high"}'

Creating a Todo with Due Date

curl -X POST "http://localhost:8000/api/v1/todos" \
     -H "Content-Type: application/json" \
     -d '{"title": "Submit report", "description": "Submit quarterly report", "due_date": "2024-12-31T23:59:59Z", "priority": "high"}'

Filtering Todos by Category

curl "http://localhost:8000/api/v1/todos?category_id=1"

Filtering Todos by Priority and Completion Status

curl "http://localhost:8000/api/v1/todos?priority=high&completed=false"

Search Todos

curl "http://localhost:8000/api/v1/todos?search=presentation"

Due Date Features

Query Parameters for /api/v1/todos

• overdue: Filter overdue todos (true/false)
• due_soon: Filter todos due within next 7 days (true/false)
• due_date_from: Filter todos due after this date (ISO format)
• due_date_to: Filter todos due before this date (ISO format)
• sort_by: Sort by due_date or created_at

Get Overdue Todos

curl "http://localhost:8000/api/v1/todos/overdue"

Get Todos Due Soon (next 7 days)

curl "http://localhost:8000/api/v1/todos/due-soon"

Get Todos Due Today

curl "http://localhost:8000/api/v1/todos/due-today"

Filter by Date Range

curl "http://localhost:8000/api/v1/todos?due_date_from=2024-01-01T00:00:00Z&due_date_to=2024-12-31T23:59:59Z"

Sort by Due Date

curl "http://localhost:8000/api/v1/todos?sort_by=due_date"

Complex Filtering Example

curl "http://localhost:8000/api/v1/todos?priority=high&overdue=true&sort_by=due_date&page=1&per_page=20"