From 646ea551068aac366ad39874389bf65b3ad872c5 Mon Sep 17 00:00:00 2001 From: Automated Action Date: Thu, 19 Jun 2025 13:23:54 +0000 Subject: [PATCH] Update README with comprehensive due date API documentation Added detailed documentation for new due date functionality: - Updated features list to include due date capabilities - Added specialized due date endpoints documentation - Documented query parameters for filtering and sorting - Added usage examples for all due date operations - Updated project structure to reflect current state - Added timezone support documentation - Included complex filtering examples --- README.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 78 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 7f87381..d5dcc7a 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,12 @@ A simple todo application built with FastAPI and SQLite. - Create, read, update, and delete todos - Category management system for organizing todos - Priority levels for todos (low, medium, high) -- Search and filtering by category, priority, and completion status +- 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 @@ -23,12 +28,22 @@ A simple todo application built with FastAPI and SQLite. - `GET /redoc` - Alternative API documentation ### Todos -- `GET /api/v1/todos` - Get all todos (with filtering by category, priority, completion status, and search) +- `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 @@ -63,11 +78,13 @@ The API will be available at `http://localhost:8000` │ │ └── v1/ │ │ ├── __init__.py │ │ ├── todos.py -│ │ └── categories.py +│ │ ├── categories.py +│ │ └── projects.py │ ├── crud/ │ │ ├── __init__.py │ │ ├── todo.py -│ │ └── category.py +│ │ ├── category.py +│ │ └── project.py │ ├── db/ │ │ ├── __init__.py │ │ ├── base.py @@ -75,17 +92,27 @@ The API will be available at `http://localhost:8000` │ ├── models/ │ │ ├── __init__.py │ │ ├── todo.py -│ │ └── category.py +│ │ ├── category.py +│ │ ├── project.py +│ │ └── tag.py │ ├── schemas/ │ │ ├── __init__.py │ │ ├── todo.py -│ │ └── category.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 +│ │ ├── 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 @@ -117,6 +144,11 @@ Each todo has the following fields: #### 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: @@ -164,3 +196,42 @@ curl "http://localhost:8000/api/v1/todos?priority=high&completed=false" ```bash 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 +```bash +curl "http://localhost:8000/api/v1/todos/overdue" +``` + +### Get Todos Due Soon (next 7 days) +```bash +curl "http://localhost:8000/api/v1/todos/due-soon" +``` + +### Get Todos Due Today +```bash +curl "http://localhost:8000/api/v1/todos/due-today" +``` + +### Filter by Date Range +```bash +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 +```bash +curl "http://localhost:8000/api/v1/todos?sort_by=due_date" +``` + +### Complex Filtering Example +```bash +curl "http://localhost:8000/api/v1/todos?priority=high&overdue=true&sort_by=due_date&page=1&per_page=20" +```