Dashboard API Reference

Complete API documentation for the Oter Dashboard endpoints.

Base URL


http://localhost:8080/api/v1

Authentication

All dashboard endpoints require JWT authentication. Include the Bearer token in the Authorization header:


Authorization: Bearer <your_jwt_token>

The token should contain a LoggedUserDTO principal with a valid userId.

Endpoints

1. Get Dashboard Data

Retrieves comprehensive dashboard data for a specific date and time.

Endpoint: GET /api/v1/dashboard

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
dateTime	string	Yes	ISO 8601 datetime format (e.g., “2024-01-16T14:30:00”)

Request Example:


GET /api/v1/dashboard?dateTime=2024-01-16T14:30:00
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

cURL Example:


curl -X GET "http://localhost:8080/api/v1/dashboard?dateTime=2024-01-16T14:30:00" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Success Response (200 OK):


{
  "nextTask": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Complete project proposal",
    "description": "Draft and review the Q1 project proposal",
    "priority": 5,
    "done": false,
    "dueDateTime": "2024-01-16T16:00:00",
    "scheduledDateTime": "2024-01-16T14:00:00"
  },
  "nextHabit": {
    "id": "223e4567-e89b-12d3-a456-426614174001",
    "name": "Morning meditation",
    "frequency": "DAILY",
    "dateTime": "2024-01-16T07:00:00",
    "done": false,
    "streak": 15
  },
  "taskStats": {
    "total": 12,
    "completed": 7,
    "highPriority": 3
  },
  "habitStats": {
    "total": 8,
    "completed": 5,
    "currentStreak": 15
  },
  "overdueTasks": 2,
  "overdueHabits": 1,
  "overdueTasksList": [
    {
      "id": "323e4567-e89b-12d3-a456-426614174002",
      "title": "Submit expense report",
      "priority": 3,
      "done": false,
      "dueDateTime": "2024-01-15T17:00:00"
    }
  ],
  "overdueHabitsList": [
    {
      "id": "423e4567-e89b-12d3-a456-426614174003",
      "name": "Evening workout",
      "frequency": "DAILY",
      "dateTime": "2024-01-15T18:00:00",
      "done": false
    }
  ],
  "recentTransactions": [
    {
      "id": "523e4567-e89b-12d3-a456-426614174004",
      "title": "Grocery shopping",
      "amount": -85.50,
      "date": "2024-01-15",
      "isIncome": false
    },
    {
      "id": "623e4567-e89b-12d3-a456-426614174005",
      "title": "Salary deposit",
      "amount": 3500.00,
      "date": "2024-01-15",
      "isIncome": true
    }
  ],
  "accountBalance": 12450.75,
  "todayCalories": 1850,
  "mealsLogged": 3,
  "nextMeal": {
    "id": "723e4567-e89b-12d3-a456-426614174006",
    "name": "Grilled chicken salad",
    "calories": 450
  },
  "todayWorkout": {
    "id": "823e4567-e89b-12d3-a456-426614174007",
    "dayOfWeek": 2,
    "exercises": [
      {
        "name": "Push-ups",
        "sets": 3,
        "reps": 15
      },
      {
        "name": "Running",
        "duration": 30,
        "distance": 5.0
      }
    ],
    "isCompleted": false
  },
  "caloriesBurned": 350,
  "workoutStreak": 7,
  "journalCompleted": true,
  "journalStreak": 12,
  "recentJournalEntries": [
    {
      "id": "923e4567-e89b-12d3-a456-426614174008",
      "date": "2024-01-16",
      "summary": "Productive day. Completed 3 major tasks."
    },
    {
      "id": "a23e4567-e89b-12d3-a456-426614174009",
      "date": "2024-01-15",
      "summary": "Feeling energized after morning workout."
    }
  ],
  "weeklyTaskCompletion": 4.2,
  "weeklyHabitCompletion": 3.8,
  "weeklyWorkoutCompletion": 0.85,
  "weeklyMealLogging": 2.7,
  "tasksCompletedPerDayThisWeek": [3, 5, 4, 6, 3, 0, 0],
  "habitsCompletedPerDayThisWeek": [4, 3, 4, 5, 3, 0, 0],
  "workoutsCompletedPerDayThisWeek": [1, 1, 0, 1, 1, 0, 0],
  "mealsLoggedPerDayThisWeek": [3, 2, 3, 4, 3, 0, 0],
  "plannedMealsPerDayThisWeek": [3, 2, 3, 3, 2, 0, 0],
  "unexpectedMealsPerDayThisWeek": [0, 0, 0, 1, 1, 0, 0]
}

Response Fields:

Field	Type	Description
nextTask	TaskDTO?	The next task to work on (based on priority algorithm)
nextHabit	HabitDTO?	The next habit to complete (based on frequency and time)
taskStats	TaskStatsDTO	Aggregate task statistics (total, completed, high priority)
habitStats	HabitStatsDTO	Aggregate habit statistics (total, completed, streak)
overdueTasks	Int	Count of tasks with due date < today
overdueHabits	Int	Count of habits past their scheduled occurrence
overdueTasksList	List	Full list of overdue tasks
overdueHabitsList	List	Full list of overdue habits
recentTransactions	List	Last 3 financial transactions
accountBalance	Double	Total balance across all accounts
todayCalories	Int	Total calories from today’s meals
mealsLogged	Int	Number of meals logged today
nextMeal	RecipeDTO?	Next scheduled meal
todayWorkout	WorkoutDayDTO?	Today’s workout plan
caloriesBurned	Int	Estimated calories burned from workouts
workoutStreak	Int	Consecutive days with completed workouts
journalCompleted	Boolean	Whether journal entry exists for today
journalStreak	Int	Consecutive days with journal entries
recentJournalEntries	List	Last 3 journal entries
weeklyTaskCompletion	Float	Average tasks completed per day this week
weeklyHabitCompletion	Float	Average habits completed per day this week
weeklyWorkoutCompletion	Float	Average workouts completed per day this week
weeklyMealLogging	Float	Average meals logged per day this week
tasksCompletedPerDayThisWeek	List	7-element array (Mon-Sun) of task counts
habitsCompletedPerDayThisWeek	List	7-element array (Mon-Sun) of habit counts
workoutsCompletedPerDayThisWeek	List	7-element array (Mon-Sun) of workout counts
mealsLoggedPerDayThisWeek	List	7-element array (Mon-Sun) of meal counts
plannedMealsPerDayThisWeek	List	7-element array (Mon-Sun) of planned meal counts
unexpectedMealsPerDayThisWeek	List	7-element array (Mon-Sun) of unexpected meal counts

Error Responses:

401 Unauthorized - Missing or invalid authentication:


"User not authenticated"

400 Bad Request - Missing dateTime parameter:


"Date parameter is required"

400 Bad Request - Invalid datetime format:


"Invalid date time format"

500 Internal Server Error:


"Internal server error"

2. Get Dashboard Configuration

Retrieves the user’s dashboard widget configuration for a specific platform.

Endpoint: GET /api/v1/dashboard/configuration

Authentication: Required

Query Parameters:

Parameter	Type	Required	Default	Description
platform	string	No	”DESKTOP”	Target platform (ANDROID, DESKTOP, WEB, IOS)

Request Example:


GET /api/v1/dashboard/configuration?platform=DESKTOP
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

cURL Example:


curl -X GET "http://localhost:8080/api/v1/dashboard/configuration?platform=DESKTOP" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Success Response (200 OK):


{
  "widgets": [
    {
      "id": "next-tasks",
      "type": "TASK_OVERVIEW",
      "title": "Next Tasks",
      "size": "LARGE",
      "enabled": true,
      "order": 0,
      "platforms": ["DESKTOP", "WEB"],
      "config": {
        "maxItems": "5",
        "showOverdue": "true"
      }
    },
    {
      "id": "habit-tracker",
      "type": "HABIT_OVERVIEW",
      "title": "Habit Tracker",
      "size": "MEDIUM",
      "enabled": true,
      "order": 1,
      "platforms": ["DESKTOP", "WEB", "ANDROID", "IOS"],
      "config": {
        "showStreak": "true"
      }
    },
    {
      "id": "finance-summary",
      "type": "FINANCE_OVERVIEW",
      "title": "Financial Summary",
      "size": "MEDIUM",
      "enabled": true,
      "order": 2,
      "platforms": ["DESKTOP", "WEB"],
      "config": {
        "showBalance": "true",
        "showRecentTransactions": "true"
      }
    }
  ],
  "gridColumns": 3,
  "platform": "DESKTOP"
}

Response Fields:

Field	Type	Description
widgets	List	Array of widget configurations
gridColumns	Int	Number of columns in grid layout (default 3)
platform	String	Platform identifier

Widget Fields:

Field	Type	Description
id	String	Unique widget identifier
type	String	Widget type (e.g., TASK_OVERVIEW, HABIT_OVERVIEW)
title	String	Display title
size	String	Widget size (SMALL, MEDIUM, LARGE)
enabled	Boolean	Visibility toggle
order	Int	Display order (ascending)
platforms	List	Supported platforms
config	Map<String, String>	Widget-specific configuration

Error Responses:

401 Unauthorized:


"User not authenticated"

404 Not Found - No configuration exists for user/platform:


"Configuration not found"

500 Internal Server Error:


"Internal server error"

3. Save Dashboard Configuration

Creates or updates the user’s dashboard widget configuration.

Endpoint: POST /api/v1/dashboard/configuration

Authentication: Required

Request Body:


{
  "configuration": {
    "widgets": [
      {
        "id": "next-tasks",
        "type": "TASK_OVERVIEW",
        "title": "My Tasks",
        "size": "LARGE",
        "enabled": true,
        "order": 0,
        "platforms": ["DESKTOP"],
        "config": {
          "maxItems": "10"
        }
      }
    ],
    "gridColumns": 3,
    "platform": "DESKTOP"
  }
}

cURL Example:


curl -X POST "http://localhost:8080/api/v1/dashboard/configuration" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "configuration": {
      "widgets": [
        {
          "id": "tasks",
          "type": "TASK_OVERVIEW",
          "title": "Tasks",
          "size": "MEDIUM",
          "enabled": true,
          "order": 0,
          "platforms": ["DESKTOP"],
          "config": {}
        }
      ],
      "gridColumns": 3,
      "platform": "DESKTOP"
    }
  }'

Success Response (200 OK):


"Configuration saved successfully"

Error Responses:

401 Unauthorized:


"User not authenticated"

500 Internal Server Error - Failed to save:


"Failed to save configuration"

500 Internal Server Error - General error:


"Internal server error"

Data Types

TaskDTO


{
  id: UUID
  title: string
  description?: string
  priority: number  // 1-5, where 5 is highest
  done: boolean
  dueDateTime?: string  // ISO 8601
  scheduledDateTime?: string  // ISO 8601
}

HabitDTO


{
  id: UUID
  name: string
  frequency: "DAILY" | "WEEKLY" | "MONTHLY" | "YEARLY"
  dateTime?: string  // ISO 8601, base occurrence
  done: boolean
  streak: number
}

TransactionDTO


{
  id: UUID
  title: string
  amount: number  // Positive for income, negative for expenses
  date: string  // ISO 8601 date
  isIncome: boolean
}

RecipeDTO


{
  id: UUID
  name: string
  calories?: number
}

WorkoutDayDTO


{
  id: UUID
  dayOfWeek: number  // 1-7 (Mon-Sun)
  exercises: Exercise[]
  isCompleted: boolean
}

JournalEntryDTO


{
  id: UUID
  date: string  // ISO 8601 date
  summary: string
}

TaskStatsDTO


{
  total: number
  completed: number
  highPriority: number  // Count of tasks with priority > 2
}

HabitStatsDTO


{
  total: number
  completed: number
  currentStreak: number  // Highest streak among all habits
}

Implementation Details

Week Calculation:

Week starts on Monday (day 1) and ends on Sunday (day 7)
Given a date, week start = date - (dayOfWeek - 1)
Week end = weekStart + 6 days

DateTime Validation:

Uses Validator.isValidDateTimeFormat(dateTime)
Must be parseable to kotlinx.datetime.LocalDateTime
Format: ISO 8601 (e.g., “2024-01-16T14:30:00”)

Per-Day Arrays:

All *PerDayThisWeek fields are 7-element arrays
Index 0 = Monday, Index 6 = Sunday
Represents counts or values for each day of the current week

Configuration Storage:

One configuration per (userId, platform) pair
Stored as JSON in DashboardConfigurations table
Supports create and update operations
Platform-agnostic storage (any string accepted)

Rate Limiting

Currently no rate limiting is implemented. Consider adding rate limiting in production environments.

Caching

Currently no caching is implemented. Dashboard data is computed fresh on each request. Consider adding caching for better performance.

Security

All endpoints require JWT authentication
User can only access their own dashboard data
User can only modify their own configurations
No cross-user data leakage