Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
372 lines (317 loc) · 7.21 KB

API_DOCUMENTATION.md

File metadata and controls

372 lines (317 loc) · 7.21 KB

Productivity Tracking System - API Documentation

Overview

The Productivity Tracking System is a full-stack web application that enables users to track daily tasks, measure productivity metrics, and visualize performance through real-time analytics.

API Endpoints

Authentication

Register

  • POST /api/auth/register/
  • Body:
{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "securepass123",
  "password2": "securepass123",
  "first_name": "John",
  "last_name": "Doe"
}

Login

  • POST /api/auth/login/
  • Body:
{
  "username": "john_doe",
  "password": "securepass123"
}
  • Response:
{
  "success": true,
  "data": {
    "id": 1,
    "username": "john_doe",
    "email": "john@example.com",
    "role": "user",
    "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
  }
}

Refresh Token

  • POST /api/auth/token/refresh/
  • Body:
{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Logout

  • POST /api/auth/logout/
  • Headers: Authorization: Bearer {access_token}

Change Password

  • POST /api/auth/change-password/
  • Headers: Authorization: Bearer {access_token}
  • Body:
{
  "old_password": "currentpass",
  "new_password": "newpass123"
}

User Management

Get Profile

  • GET /api/users/me/
  • Headers: Authorization: Bearer {access_token}

Update Profile

  • PUT /api/users/me/update/
  • Headers: Authorization: Bearer {access_token}
  • Body:
{
  "email": "newemail@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "+1234567890",
  "bio": "Software developer"
}

Get Preferences

  • GET /api/users/me/preferences/
  • Headers: Authorization: Bearer {access_token}

Update Preferences

  • PUT /api/users/me/preferences/
  • Headers: Authorization: Bearer {access_token}
  • Body:
{
  "theme": "dark",
  "notifications_enabled": true,
  "email_notifications": false,
  "daily_digest": true,
  "timezone": "UTC",
  "items_per_page": 20
}

Tasks

List Tasks

  • GET /api/tasks/?status=in_progress&priority=high&search=bug&page=1
  • Headers: Authorization: Bearer {access_token}
  • Query Parameters:
    • status: todo, in_progress, completed, cancelled
    • priority: low, medium, high, urgent
    • search: search in title/description
    • page: pagination

Create Task

  • POST /api/tasks/
  • Headers: Authorization: Bearer {access_token}
  • Body:
{
  "title": "Complete project proposal",
  "description": "Draft and finalize the proposal",
  "status": "todo",
  "priority": "high",
  "estimated_time": 4.5,
  "due_date": "2024-01-31T18:00:00Z",
  "tags": "work,urgent",
  "is_recurring": false
}

Get Task Details

  • GET /api/tasks/{id}/
  • Headers: Authorization: Bearer {access_token}

Update Task

  • PUT /api/tasks/{id}/
  • Headers: Authorization: Bearer {access_token}

Mark Task Completed

  • POST /api/tasks/{id}/mark_completed/
  • Headers: Authorization: Bearer {access_token}

Get Today's Tasks

  • GET /api/tasks/today/
  • Headers: Authorization: Bearer {access_token}

Get Overdue Tasks

  • GET /api/tasks/overdue/
  • Headers: Authorization: Bearer {access_token}

Time Tracking

Create Time Session

  • POST /api/tasks/sessions/
  • Headers: Authorization: Bearer {access_token}
  • Body:
{
  "task": 1,
  "notes": "Started working on the task"
}

Stop Time Session

  • POST /api/tasks/sessions/{id}/stop/
  • Headers: Authorization: Bearer {access_token}

Get Active Sessions

  • GET /api/tasks/sessions/active/
  • Headers: Authorization: Bearer {access_token}

Analytics

Productivity Metrics

  • GET /api/analytics/metrics/?date_from=2024-01-01&date_to=2024-01-31
  • Headers: Authorization: Bearer {access_token}
  • Query Parameters:
    • date_from: YYYY-MM-DD format
    • date_to: YYYY-MM-DD format

Daily Statistics

  • GET /api/analytics/daily/?date=2024-01-15
  • Headers: Authorization: Bearer {access_token}

Weekly Statistics

  • GET /api/analytics/weekly/
  • Headers: Authorization: Bearer {access_token}

Monthly Statistics

  • GET /api/analytics/monthly/
  • Headers: Authorization: Bearer {access_token}

Task Analytics

  • GET /api/analytics/tasks/
  • Headers: Authorization: Bearer {access_token}

Productivity Logs

Create Daily Log

  • POST /api/tasks/logs/
  • Headers: Authorization: Bearer {access_token}
  • Body:
{
  "date": "2024-01-15",
  "tasks_completed": 5,
  "tasks_planned": 6,
  "mood": "good",
  "notes": "Good day, completed most tasks"
}

Get Today's Log

  • GET /api/tasks/logs/today/
  • Headers: Authorization: Bearer {access_token}

Get Week's Logs

  • GET /api/tasks/logs/week/
  • Headers: Authorization: Bearer {access_token}

Get Month's Logs

  • GET /api/tasks/logs/month/
  • Headers: Authorization: Bearer {access_token}

Database Schema

Users Table

  • id (PK)
  • username (unique)
  • email (unique)
  • password_hash
  • first_name
  • last_name
  • phone_number
  • role (user, admin)
  • profile_picture
  • bio
  • created_at
  • updated_at

Tasks Table

  • id (PK)
  • user_id (FK)
  • title
  • description
  • status (todo, in_progress, completed, cancelled)
  • priority (low, medium, high, urgent)
  • estimated_time
  • actual_time
  • due_date
  • completed_at
  • tags
  • is_recurring
  • recurrence_pattern
  • created_at
  • updated_at

Time Tracking Sessions

  • id (PK)
  • task_id (FK)
  • user_id (FK)
  • status (started, paused, stopped)
  • duration
  • start_time
  • end_time
  • notes
  • created_at

Daily Productivity Logs

  • id (PK)
  • user_id (FK)
  • date
  • tasks_completed
  • tasks_planned
  • total_time_spent
  • total_time_planned
  • productivity_score (0-100)
  • mood
  • notes
  • created_at
  • updated_at

WebSocket Events

Task Updates

  • Connect to: ws://localhost:8000/ws/tasks/
  • Message Types:
    • task_update: Task status or details changed
    • task_created: New task created
    • task_deleted: Task deleted
    • productivity_update: Productivity log updated

Example WebSocket Message

{
  "action": "task_update",
  "task_id": 1,
  "updates": {
    "status": "in_progress",
    "actual_time": 2.5
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "message": "Validation error",
  "data": {
    "field_name": ["Error message"]
  }
}

401 Unauthorized

{
  "success": false,
  "message": "Invalid credentials or expired token"
}

403 Forbidden

{
  "success": false,
  "message": "Permission denied"
}

404 Not Found

{
  "success": false,
  "message": "Resource not found"
}

Rate Limiting

  • Default: 1000 requests per hour per IP
  • Authenticated users: 5000 requests per hour

Pagination

Default page size: 20 items

Query parameters:

  • page: page number (default: 1)
  • limit: items per page (default: 20, max: 100)

Response format:

{
  "success": true,
  "data": [],
  "count": 100,
  "next": "http://api/tasks/?page=2",
  "previous": null
}