347 lines
11 KiB
Markdown
347 lines
11 KiB
Markdown
# 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ásica
|
|
- `GET /health` - Endpoint de verificación de salud
|
|
- `GET /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ón
|
|
- `POST /api/v1/todos` - Crear una nueva tarea
|
|
- `GET /api/v1/todos/{todo_id}` - Obtener una tarea específica
|
|
- `PUT /api/v1/todos/{todo_id}` - Actualizar una tarea específica
|
|
- `DELETE /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ías
|
|
- `POST /api/v1/categories` - Crear nueva categoría
|
|
- `GET /api/v1/categories/{category_id}` - Obtener categoría específica
|
|
- `PUT /api/v1/categories/{category_id}` - Actualizar categoría
|
|
- `DELETE /api/v1/categories/{category_id}` - Eliminar categoría
|
|
|
|
### Gestión de Etiquetas (`/api/v1/tags`)
|
|
- `GET /api/v1/tags` - Listar todas las etiquetas
|
|
- `POST /api/v1/tags` - Crear nueva etiqueta
|
|
- `GET /api/v1/tags/{tag_id}` - Obtener etiqueta específica
|
|
- `PUT /api/v1/tags/{tag_id}` - Actualizar etiqueta
|
|
- `DELETE /api/v1/tags/{tag_id}` - Eliminar etiqueta
|
|
- `POST /api/v1/tags/{tag_id}/todos/{todo_id}` - Agregar etiqueta a tarea
|
|
- `DELETE /api/v1/tags/{tag_id}/todos/{todo_id}` - Quitar etiqueta de tarea
|
|
- `GET /api/v1/tags/{tag_id}/todos` - Obtener tareas por etiqueta
|
|
|
|
### Gestión de Proyectos (`/api/v1/projects`)
|
|
- `GET /api/v1/projects` - Listar todos los proyectos
|
|
- `POST /api/v1/projects` - Crear nuevo proyecto
|
|
- `GET /api/v1/projects/{project_id}` - Obtener proyecto específico
|
|
- `PUT /api/v1/projects/{project_id}` - Actualizar proyecto
|
|
- `DELETE /api/v1/projects/{project_id}` - Eliminar proyecto
|
|
- `GET /api/v1/projects/{project_id}/todos` - Obtener tareas del proyecto
|
|
- `PUT /api/v1/projects/{project_id}/archive` - Archivar proyecto
|
|
|
|
### Gestión de Subtareas
|
|
- `POST /api/v1/todos/{todo_id}/subtasks` - Crear subtarea
|
|
- `GET /api/v1/todos/{todo_id}/subtasks` - Obtener subtareas
|
|
- `PUT /api/v1/subtasks/{subtask_id}/move` - Mover subtarea
|
|
|
|
## Instalación
|
|
|
|
1. Instalar las dependencias:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
2. Configurar variables de entorno:
|
|
```bash
|
|
cp .env.example .env
|
|
# Editar .env con tu configuración local
|
|
```
|
|
|
|
3. Ejecutar migraciones de base de datos:
|
|
```bash
|
|
alembic upgrade head
|
|
```
|
|
|
|
4. Iniciar la aplicación:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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ía
|
|
- `project_id` - Filtrar por proyecto
|
|
- `search` - Buscar en título y descripción
|
|
- `parent_id` - Filtrar por tarea padre (null para tareas principales)
|
|
|
|
### Formato de Respuesta con Paginación
|
|
|
|
```json
|
|
{
|
|
"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ón
|
|
- `updated_at`: Marca de tiempo de última actualización
|
|
|
|
#### Tabla `categories`
|
|
- `id`: Identificador único
|
|
- `name`: 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 único
|
|
- `name`: 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 único
|
|
- `name`: 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 tarea
|
|
- `tag_id`: Referencia a etiqueta
|
|
- Relación muchos-a-muchos entre tareas y etiquetas
|
|
|
|
## Ejemplos de Uso
|
|
|
|
### Crear una Categoría
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
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
|
|
```bash
|
|
# 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 SQLite
|
|
- `APP_TITLE`: Título de la aplicación
|
|
- `CORS_ORIGINS`: Orígenes permitidos para CORS
|
|
- `HOST` y `PORT`: Configuración del servidor
|
|
- `LOG_LEVEL`: Nivel de logging
|
|
|
|
## Contribuir
|
|
|
|
Por favor, lee [CONTRIBUTING.md](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](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:
|
|
|
|
1. **Capa de API** (`app/api/`): Endpoints de FastAPI y manejo de requests
|
|
2. **Capa de Esquemas** (`app/schemas/`): Validación de datos con Pydantic
|
|
3. **Capa de CRUD** (`app/crud/`): Operaciones de base de datos
|
|
4. **Capa de Modelos** (`app/models/`): Modelos de SQLAlchemy
|
|
5. **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:
|
|
|
|
1. Clonar el repositorio
|
|
2. Configurar entorno virtual
|
|
3. Instalar dependencias
|
|
4. Configurar variables de entorno
|
|
5. Ejecutar migraciones
|
|
6. Iniciar servidor de desarrollo
|
|
|
|
La aplicación incluye recarga automática durante el desarrollo y documentación interactiva disponible en `/docs`. |