11 KiB
API Simple de Tareas (Todo)
Una aplicación simple de tareas construida con FastAPI y SQLite.
Características
- Crear, leer, actualizar y eliminar tareas
- Base de datos SQLite con ORM SQLAlchemy
- Migraciones de base de datos con Alembic
- FastAPI con documentación automática OpenAPI
- CORS habilitado para todos los orígenes
- Endpoint de verificación de salud
- Sistema de categorías - Clasificación simple de tareas
- Sistema de etiquetas - Etiquetado múltiple flexible
- Sistema de subtareas - Descomposición jerárquica de tareas
- Sistema de proyectos - Agrupación de tareas con metadatos
- Niveles de prioridad - Prioridades alta, media y baja
- Paginación avanzada - Con metadatos de respuesta
- Búsqueda y filtrado - Múltiples criterios de filtrado
Endpoints de la API
Endpoints Principales
GET /
- Endpoint raíz con información básicaGET /health
- Endpoint de verificación de saludGET /docs
- Documentación interactiva de la API (Swagger UI)GET /redoc
- Documentación alternativa de la API
Gestión de Tareas (/api/v1/todos
)
GET /api/v1/todos
- Obtener todas las tareas con filtrado y paginaciónPOST /api/v1/todos
- Crear una nueva tareaGET /api/v1/todos/{todo_id}
- Obtener una tarea específicaPUT /api/v1/todos/{todo_id}
- Actualizar una tarea específicaDELETE /api/v1/todos/{todo_id}
- Eliminar una tarea específica
Gestión de Categorías (/api/v1/categories
)
GET /api/v1/categories
- Listar todas las categoríasPOST /api/v1/categories
- Crear nueva categoríaGET /api/v1/categories/{category_id}
- Obtener categoría específicaPUT /api/v1/categories/{category_id}
- Actualizar categoríaDELETE /api/v1/categories/{category_id}
- Eliminar categoría
Gestión de Etiquetas (/api/v1/tags
)
GET /api/v1/tags
- Listar todas las etiquetasPOST /api/v1/tags
- Crear nueva etiquetaGET /api/v1/tags/{tag_id}
- Obtener etiqueta específicaPUT /api/v1/tags/{tag_id}
- Actualizar etiquetaDELETE /api/v1/tags/{tag_id}
- Eliminar etiquetaPOST /api/v1/tags/{tag_id}/todos/{todo_id}
- Agregar etiqueta a tareaDELETE /api/v1/tags/{tag_id}/todos/{todo_id}
- Quitar etiqueta de tareaGET /api/v1/tags/{tag_id}/todos
- Obtener tareas por etiqueta
Gestión de Proyectos (/api/v1/projects
)
GET /api/v1/projects
- Listar todos los proyectosPOST /api/v1/projects
- Crear nuevo proyectoGET /api/v1/projects/{project_id}
- Obtener proyecto específicoPUT /api/v1/projects/{project_id}
- Actualizar proyectoDELETE /api/v1/projects/{project_id}
- Eliminar proyectoGET /api/v1/projects/{project_id}/todos
- Obtener tareas del proyectoPUT /api/v1/projects/{project_id}/archive
- Archivar proyecto
Gestión de Subtareas
POST /api/v1/todos/{todo_id}/subtasks
- Crear subtareaGET /api/v1/todos/{todo_id}/subtasks
- Obtener subtareasPUT /api/v1/subtasks/{subtask_id}/move
- Mover subtarea
Instalación
- Instalar las dependencias:
pip install -r requirements.txt
- Configurar variables de entorno:
cp .env.example .env
# Editar .env con tu configuración local
- Ejecutar migraciones de base de datos:
alembic upgrade head
- Iniciar la aplicación:
uvicorn main:app --reload
La API estará disponible en http://localhost:8000
Filtrado y Búsqueda Avanzados
Parámetros de Consulta Disponibles
La API soporta filtrado y búsqueda sofisticados:
GET /api/v1/todos?page=1&per_page=10&completed=false&priority=high&category_id=1&project_id=2&search=urgente&parent_id=null
Parámetros:
page
- Número de página (predeterminado: 1)per_page
- Elementos por página (predeterminado: 10, máximo: 100)completed
- Filtrar por estado de completado (true/false)priority
- Filtrar por prioridad (high/medium/low)category_id
- Filtrar por categoríaproject_id
- Filtrar por proyectosearch
- Buscar en título y descripciónparent_id
- Filtrar por tarea padre (null para tareas principales)
Formato de Respuesta con Paginación
{
"items": [...tareas...],
"total": 25,
"page": 1,
"per_page": 10,
"has_next": true,
"has_prev": false
}
Estructura del Proyecto
├── app/
│ ├── api/
│ │ └── v1/
│ │ ├── __init__.py
│ │ ├── todos.py
│ │ ├── categories.py
│ │ ├── tags.py
│ │ └── projects.py
│ ├── crud/
│ │ ├── __init__.py
│ │ ├── todo.py
│ │ ├── category.py
│ │ ├── tag.py
│ │ └── project.py
│ ├── db/
│ │ ├── __init__.py
│ │ ├── base.py
│ │ └── session.py
│ ├── models/
│ │ ├── __init__.py
│ │ ├── todo.py
│ │ ├── category.py
│ │ ├── tag.py
│ │ ├── todo_tag.py
│ │ └── project.py
│ ├── schemas/
│ │ ├── __init__.py
│ │ ├── todo.py
│ │ ├── category.py
│ │ ├── tag.py
│ │ └── project.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
│ ├── env.py
│ └── script.py.mako
├── .github/
│ └── pull_request_template.md
├── alembic.ini
├── main.py
├── requirements.txt
├── .env.example
├── LICENSE
├── CONTRIBUTING.md
├── README.md
└── README-es.md
Base de Datos
La aplicación utiliza una base de datos SQLite almacenada en /app/storage/db/db.sqlite
. El esquema de la base de datos se gestiona usando migraciones de Alembic.
Esquema de Base de Datos
Tabla todos
(Principal)
id
: Identificador único (generado automáticamente)title
: Título de la tarea (requerido, máximo 200 caracteres)description
: Descripción de la tarea (opcional, máximo 500 caracteres)completed
: Estado de completado (booleano, predeterminado: false)priority
: Nivel de prioridad (high/medium/low, predeterminado: medium)category_id
: Referencia a categoría (opcional)project_id
: Referencia a proyecto (opcional)parent_id
: Referencia a tarea padre para subtareas (opcional)created_at
: Marca de tiempo de creaciónupdated_at
: Marca de tiempo de última actualización
Tabla categories
id
: Identificador úniconame
: Nombre de la categoría (único, máximo 100 caracteres)description
: Descripción de la categoría (opcional)color
: Código de color hexadecimal (opcional)created_at
,updated_at
: Marcas de tiempo
Tabla tags
id
: Identificador úniconame
: Nombre de la etiqueta (único, máximo 50 caracteres)color
: Código de color hexadecimal (opcional)created_at
: Marca de tiempo de creación
Tabla projects
id
: Identificador úniconame
: Nombre del proyecto (máximo 200 caracteres)description
: Descripción del proyecto (opcional)status
: Estado del proyecto (active/archived)created_at
,updated_at
: Marcas de tiempo
Tabla todo_tags
(Asociación)
todo_id
: Referencia a tareatag_id
: Referencia a etiqueta- Relación muchos-a-muchos entre tareas y etiquetas
Ejemplos de Uso
Crear una Categoría
curl -X POST "http://localhost:8000/api/v1/categories" \
-H "Content-Type: application/json" \
-d '{
"name": "Trabajo",
"description": "Tareas relacionadas con el trabajo",
"color": "#FF6B6B"
}'
Crear un Proyecto
curl -X POST "http://localhost:8000/api/v1/projects" \
-H "Content-Type: application/json" \
-d '{
"name": "Rediseño del Sitio Web",
"description": "Proyecto completo de rediseño"
}'
Crear una Tarea con Categoría y Proyecto
curl -X POST "http://localhost:8000/api/v1/todos" \
-H "Content-Type: application/json" \
-d '{
"title": "Revisar presentación",
"description": "Revisar la presentación del cliente",
"priority": "high",
"category_id": 1,
"project_id": 1
}'
Crear Etiquetas y Asignarlas
# Crear etiqueta
curl -X POST "http://localhost:8000/api/v1/tags" \
-H "Content-Type: application/json" \
-d '{
"name": "urgente",
"color": "#FF0000"
}'
# Asignar etiqueta a tarea
curl -X POST "http://localhost:8000/api/v1/tags/1/todos/1"
Crear Subtarea
curl -X POST "http://localhost:8000/api/v1/todos/1/subtasks" \
-H "Content-Type: application/json" \
-d '{
"title": "Revisar sección de introducción",
"priority": "medium"
}'
Filtrar Tareas
# Obtener tareas de alta prioridad en proyecto específico
curl "http://localhost:8000/api/v1/todos?project_id=1&priority=high&completed=false"
# Buscar tareas con texto específico
curl "http://localhost:8000/api/v1/todos?search=revisar&category_id=1"
# Obtener solo tareas principales (sin subtareas)
curl "http://localhost:8000/api/v1/todos?parent_id=null"
Variables de Entorno
Consulta .env.example
para ver todas las variables de configuración disponibles:
DATABASE_URL
: URL de la base de datos SQLiteAPP_TITLE
: Título de la aplicaciónCORS_ORIGINS
: Orígenes permitidos para CORSHOST
yPORT
: Configuración del servidorLOG_LEVEL
: Nivel de logging
Contribuir
Por favor, lee CONTRIBUTING.md para obtener detalles sobre nuestro código de conducta y el proceso para enviar pull requests.
Licencia
Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.
Características Técnicas
- FastAPI: Framework web moderno y rápido
- SQLAlchemy: ORM potente para Python
- Alembic: Gestión de migraciones de base de datos
- Pydantic: Validación de datos y serialización
- Ruff: Formateador y linter de código
- SQLite: Base de datos ligera y confiable
Arquitectura
La aplicación sigue un patrón de arquitectura en capas:
- Capa de API (
app/api/
): Endpoints de FastAPI y manejo de requests - Capa de Esquemas (
app/schemas/
): Validación de datos con Pydantic - Capa de CRUD (
app/crud/
): Operaciones de base de datos - Capa de Modelos (
app/models/
): Modelos de SQLAlchemy - Capa de Base de Datos (
app/db/
): Configuración de conexión
Esta arquitectura proporciona separación clara de responsabilidades y facilita el mantenimiento y las pruebas.
Desarrollo
Para desarrollo local:
- Clonar el repositorio
- Configurar entorno virtual
- Instalar dependencias
- Configurar variables de entorno
- Ejecutar migraciones
- Iniciar servidor de desarrollo
La aplicación incluye recarga automática durante el desarrollo y documentación interactiva disponible en /docs
.