Skip to content

saidibnerradi603/task-manager-api

BranchesTags

Repository files navigation

Task Manager API

A RESTful API for task and to-do list management built with FastAPI, PostgreSQL, and SQLAlchemy. Features JWT authentication, role-based access control, and comprehensive task organization with folders and tags.

Features

  • User Management: Secure registration, authentication, and profile management
  • Task Organization: Create, update, and track tasks with status and priority levels
  • Folder System: Organize tasks into custom folders
  • Tag System: Categorize tasks with reusable tags
  • Advanced Filtering: Search and filter tasks by status, priority, folder, tags, and text
  • JWT Authentication: Secure access with access/refresh token rotation
  • Role-Based Access Control: User and Admin roles with permission enforcement
  • Database Migrations: Alembic-powered schema versioning
  • Comprehensive Validation: Pydantic schemas with custom validators

Architecture

System Architecture

graph TB
    Client[Client]
    
    subgraph FastAPI Application
        Routes[Routes<br/>API Endpoints]
        Deps[Dependencies<br/>Auth & DB]
        Services[Services<br/>Business Logic]
        Repos[Repositories<br/>Data Access]
    end
    
    DB[(PostgreSQL)]
    
    Client -->|HTTP Request| Routes
    Routes -->|Depends| Deps
    Deps -->|Inject| Routes
    Routes -->|Call| Services
    Services -->|Use| Repos
    Repos -->|SQLAlchemy| DB
    
    style Routes fill:#4CAF50
    style Services fill:#2196F3
    style Repos fill:#9C27B0
    style DB fill:#F44336
    style Deps fill:#FF9800
Loading

Project Structure

.
├── core/                   # Core application configuration
│   ├── config.py          # Settings and environment variables
│   ├── db.py              # Database connection and session management
│   ├── security.py        # JWT and password hashing utilities
│   ├── exceptions.py      # Custom exception classes
│   └── responses.py       # Reusable API response schemas
│
├── models/                 # SQLAlchemy ORM models
│   ├── base.py            # Declarative base
│   ├── mixins.py          # Reusable model mixins (UUID, Timestamp)
│   ├── user.py            # User model
│   ├── task.py            # Task model
│   ├── folder.py          # Folder model
│   ├── tag.py             # Tag model
│   └── task_tag.py        # Many-to-many association table
│
├── schemas/                # Pydantic validation schemas
│   ├── user.py            # User request/response schemas
│   ├── task.py            # Task request/response schemas
│   ├── folder.py          # Folder request/response schemas
│   ├── tag.py             # Tag request/response schemas
│   └── token.py           # JWT token schemas
│
├── repositories/           # Data access layer
│   ├── base.py            # Generic CRUD operations
│   ├── user.py            # User-specific queries
│   ├── task.py            # Task-specific queries with filtering
│   ├── folder.py          # Folder-specific queries
│   └── tag.py             # Tag-specific queries
│
├── services/               # Business logic layer
│   ├── auth_service.py    # Authentication and token management
│   ├── user_service.py    # User management operations
│   ├── task_service.py    # Task CRUD with validation
│   ├── folder_service.py  # Folder management
│   └── tag_service.py     # Tag management
│
├── routes/                 # API endpoints
│   ├── auth_route.py      # /auth/* - Login, signup, token refresh
│   ├── user_route.py      # /users/* - User management
│   ├── task_route.py      # /tasks/* - Task operations
│   ├── folder_route.py    # /folders/* - Folder operations
│   └── tag_route.py       # /tags/* - Tag operations
│
├── utils/                  # Utility modules
│   ├── deps.py            # FastAPI dependencies (auth, RBAC)
│   ├── enums.py           # Enums (UserRole, TaskStatus, TaskPriority,TokenType)
│   └── validators.py      # Custom validation functions
│
├── migrations/             # Alembic database migrations
│   └── versions/          # Migration scripts
│
├── main.py                 # Application entry point
├── requirements.txt        # Python dependencies
├── alembic.ini            # Alembic configuration
└── .env.example           # Environment variables template

Database Schema

erDiagram
    USERS ||--o{ FOLDERS : "creates"
    USERS ||--o{ TASKS : "owns"
    USERS ||--o{ TAGS : "defines"
    
    FOLDERS ||--o{ TASKS : "contains"
    TASKS ||--o{ TASK_TAGS : "has"
    TAGS ||--o{ TASK_TAGS : "labeled with"

    USERS {
        UUID id PK "DEFAULT gen_uuid()"
        VARCHAR email UK "UNIQUE, NOT NULL"
        VARCHAR username UK "UNIQUE, NOT NULL"
        VARCHAR password_hash "NOT NULL"
        BOOLEAN is_active "DEFAULT true"
        ENUM role "DEFAULT 'user'"
        TIMESTAMP created_at "DEFAULT now()"
        TIMESTAMP updated_at 
    }

    FOLDERS {
        UUID id PK "DEFAULT gen_uuid()"
        UUID user_id FK 
        VARCHAR name "NOT NULL, UK(user_id, name)"
        TIMESTAMP created_at "DEFAULT now()"
        TIMESTAM updated_at
    }

    TASKS {
        UUID id PK "DEFAULT gen_uuid()"
        UUID user_id FK 
        UUID folder_id FK "NULLABLE"
        VARCHAR title "NOT NULL"
        TEXT description "NULLABLE"
        ENUM status "DEFAULT 'todo'"
        ENUM priority "DEFAULT 'medium'"
        TIMESTAMP due_date "NULLABLE"
        TIMESTAMP created_at "DEFAULT now()"
        TIMESTAMP updated_at 
    }

    TAGS {
        UUID id PK "DEFAULT gen_uuid()"
        UUID user_id FK 
        VARCHAR name "NOT NULL, UK(user_id, name)"
    }

    TASK_TAGS {
        UUID task_id FK, PK 
        UUID tag_id FK, PK 
    }
Loading

Getting Started

Prerequisites

  • Python 3.10+
  • PostgreSQL
  • pip or uv package manager

Installation

  1. Clone the repository
git clone https://github.com/saidibnerradi603/task-manager-api.git
cd task-manager-api
  1. Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Install dependencies
pip install -r requirements.txt
  1. Configure environment variables
cp .env.example .env

Edit .env with your configuration:

# Database
DB_USER=postgres
DB_PASSWORD=your_secure_password
DB_HOST=localhost
DB_PORT=5432
DB_NAME=tasks

# Security
SECRET_KEY=your_secret_key_here_min_32_chars
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7
HASH_ALGORITHM=bcrypt
  1. Set up the database
createdb tasks
  1. Run database migrations

Alembic will create all tables (users, tasks, folders, tags, task_tags) with proper relationships:

alembic upgrade head
  1. Start the server
uvicorn main:app --reload

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

API Documentation

Interactive Documentation

Authentication Flow

sequenceDiagram
    participant Client
    participant API
    participant DB
    
    Client->>API: POST /auth/signup
    API->>DB: Create user
    DB-->>API: User created
    API-->>Client: UserResponse
    
    Client->>API: POST /auth/login
    API->>DB: Validate credentials
    DB-->>API: User valid
    API-->>Client: Access Token + Refresh Cookie
    
    Client->>API: GET /users/me (with token)
    API->>API: Validate JWT
    API->>DB: Fetch user
    DB-->>API: User data
    API-->>Client: UserResponse
    
    Client->>API: POST /auth/refresh (with cookie)
    API->>API: Validate refresh token
    API-->>Client: New Access Token + New Refresh Cookie
Loading

Core Endpoints

Authentication (/api/v1/auth)

Method Endpoint Description Auth Required
POST /signup Register new user No
POST /login Login and get tokens No
POST /refresh Refresh access token Refresh Token
POST /logout Clear refresh cookie No

Users (/api/v1/users)

Method Endpoint Description Auth Required
GET /me Get current user profile Yes
PATCH /me Update profile Yes
PUT /me/change-password Change password Yes
GET / List all users Admin only
GET /{user_id} Get user by ID Admin only

Tasks (/api/v1/tasks)

Method Endpoint Description Auth Required
POST / Create task Yes
GET / List/filter tasks Yes
GET /{task_id} Get task details Yes
PATCH /{task_id} Update task Yes
DELETE /{task_id} Delete task Yes

Task Filtering Parameters:

  • search: Text search in title/description
  • status: Filter by status (todo, in_progress, done)
  • priority: Filter by priority (low, medium, high, urgent)
  • folder_id: Filter by folder
  • tag_id: Filter by tag
  • skip / limit: Pagination

Folders (/api/v1/folders)

Method Endpoint Description Auth Required
POST / Create folder Yes
GET / List folders Yes
GET /{folder_id} Get folder details Yes
PATCH /{folder_id} Update folder Yes
DELETE /{folder_id} Delete folder Yes

Tags (/api/v1/tags)

Method Endpoint Description Auth Required
POST / Create tag Yes
GET / List tags Yes
GET /{tag_id} Get tag details Yes
DELETE /{tag_id} Delete tag Yes

Example Requests

1. Register User

curl -X POST "http://localhost:8000/api/v1/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!"
  }'

2. Login

curl -X POST "http://localhost:8000/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=user@example.com&password=SecurePass123!"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

3. Create Task

curl -X POST "http://localhost:8000/api/v1/tasks" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Complete project documentation",
    "description": "Write comprehensive README",
    "status": "todo",
    "priority": "high",
    "due_date": "2026-02-20T17:00:00Z",
    "folder_id": null,
    "tag_ids": []
  }'

4. Filter Tasks

curl -X GET "http://localhost:8000/api/v1/tasks?status=todo&priority=high&search=documentation" \
  -H "Authorization: Bearer <access_token>"

Dependencies

Core dependencies:

  • FastAPI: Modern web framework
  • SQLAlchemy: ORM and database toolkit
  • Alembic: Database migration tool
  • Pydantic: Data validation
  • python-jose: JWT implementation
  • passlib: Password hashing
  • psycopg2: PostgreSQL adapter

See requirements.txt for complete list.

About

A RESTful API for task and to-do list management built with FastAPI, PostgreSQL, and SQLAlchemy. Features JWT authentication, role-based access control, and task organization with folders and tags.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages