yadunut/system
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases Wiki Activity
5e1d72bf2c
system/docs/api.md

21 KiB
Raw Blame History

Personal System API Documentation

Overview

This API serves a personal productivity system with habit tracking and intake metrics. The system supports three client types:

  • TUI (Terminal User Interface): Command-line interface for quick interactions
  • Mobile App: Native mobile application for on-the-go tracking
  • Web Application: Rich web interface with analytics and reporting

Base URL

Production: https://api.personal-system.com/v1
Development: http://localhost:3000/api/v1

Authentication

All endpoints require authentication via JWT tokens passed in the Authorization header:

Authorization: Bearer <jwt_token>

Authentication Endpoints

Login

POST /auth/login

Request Body:

{
  "email": "user@example.com",
  "password": "securepassword"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user-uuid",
    "username": "johndoe",
    "email": "user@example.com"
  },
  "expires_at": "2024-01-15T12:00:00Z"
}

Refresh Token

POST /auth/refresh

Request Body:

{
  "refresh_token": "refresh_token_here"
}

Logout

POST /auth/logout

Common Patterns

Pagination

List endpoints support pagination with the following parameters:

  • limit: Number of items per page (default: 50, max: 100)
  • offset: Number of items to skip (default: 0)
  • cursor: Cursor-based pagination for real-time data

Example:

GET /api/habits?limit=20&offset=40

Filtering

Most endpoints support filtering via query parameters:

  • fields: Select specific fields to return
  • active: Filter by active status (true/false)
  • start_date: Filter by start date (ISO 8601)
  • end_date: Filter by end date (ISO 8601)

Example:

GET /api/habits?fields=id,name,active&active=true

Response Format

All responses follow this structure:

{
  "data": [], // or {} for single items
  "meta": {
    "total": 100,
    "limit": 20,
    "offset": 40,
    "has_more": true
  },
  "links": {
    "self": "/api/habits?limit=20&offset=40",
    "next": "/api/habits?limit=20&offset=60",
    "prev": "/api/habits?limit=20&offset=20"
  }
}

Error Handling

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "target_count",
        "message": "Must be a positive integer"
      }
    ],
    "request_id": "req-uuid"
  }
}

HTTP Status Codes

  • 200 OK: Success
  • 201 Created: Resource created successfully
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 409 Conflict: Resource already exists
  • 422 Unprocessable Entity: Validation error
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error

Rate Limiting

Rate limits are enforced per client type:

  • TUI: 100 requests per minute
  • Mobile: 200 requests per minute
  • Web: 300 requests per minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642262400

Caching

ETags

Most GET endpoints support ETags for efficient caching:

ETag: "33a64df551"

Use the If-None-Match header to check for updates:

If-None-Match: "33a64df551"

Cache Headers

Cache-Control: max-age=300, private
Last-Modified: Mon, 15 Jan 2024 10:00:00 GMT

Habits API

Core Endpoints

List Habits

GET /api/habits

Query Parameters:

  • active: Filter by active status (true/false)
  • frequency_type: Filter by frequency type (daily/interval/multi_daily)
  • fields: Select specific fields
  • limit, offset: Pagination

Response:

{
  "data": [
    {
      "id": "habit-uuid",
      "name": "Take vitamins",
      "description": "Daily vitamin supplement",
      "frequency_type": "daily",
      "target_count": 1,
      "interval_days": null,
      "active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "total": 5,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Get Habit

GET /api/habits/{habit_id}

Response:

{
  "data": {
    "id": "habit-uuid",
    "name": "Take vitamins",
    "description": "Daily vitamin supplement",
    "frequency_type": "daily",
    "target_count": 1,
    "interval_days": null,
    "active": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Create Habit

POST /api/habits

Request Body:

{
  "name": "Morning meditation",
  "description": "15 minutes of mindfulness",
  "frequency_type": "daily",
  "target_count": 1
}

Response: 201 Created with the created habit object.

Update Habit

PUT /api/habits/{habit_id}

Request Body:

{
  "name": "Updated habit name",
  "description": "Updated description",
  "active": false
}

Delete Habit

DELETE /api/habits/{habit_id}

Response: 204 No Content

Habit Completions

List Completions

GET /api/habits/{habit_id}/completions

Query Parameters:

  • start_date: ISO 8601 date
  • end_date: ISO 8601 date
  • limit, offset: Pagination

Response:

{
  "data": [
    {
      "id": "completion-uuid",
      "habit_id": "habit-uuid",
      "completed_at": "2024-01-15T08:30:00Z",
      "notes": "Completed during lunch break",
      "created_at": "2024-01-15T08:30:00Z"
    }
  ],
  "meta": {
    "total": 30,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Create Completion

POST /api/habits/{habit_id}/completions

Request Body:

{
  "completed_at": "2024-01-15T08:30:00Z",
  "notes": "Completed during lunch break"
}

Response: 201 Created with the completion object.

Bulk Create Completions

POST /api/habits/completions/bulk

Request Body:

{
  "completions": [
    {
      "habit_id": "habit-uuid-1",
      "completed_at": "2024-01-15T08:30:00Z",
      "notes": "Morning habit"
    },
    {
      "habit_id": "habit-uuid-2",
      "completed_at": "2024-01-15T09:00:00Z"
    }
  ]
}

Habit Status

Get Habit Status

GET /api/habits/{habit_id}/status

Response:

{
  "data": {
    "habit_id": "habit-uuid",
    "completed_today": true,
    "completions_today": 2,
    "target_count": 2,
    "completion_rate": 1.0,
    "current_streak": 15,
    "longest_streak": 30,
    "next_due_date": null,
    "last_completed_at": "2024-01-15T08:30:00Z",
    "status": "completed"
  }
}

Get All Habits Status

GET /api/habits/status

Response:

{
  "data": [
    {
      "habit_id": "habit-uuid",
      "name": "Take vitamins",
      "completed_today": true,
      "completions_today": 1,
      "target_count": 1,
      "status": "completed"
    }
  ]
}

Bulk Status Check

POST /api/habits/status/bulk

Request Body:

{
  "habit_ids": ["habit-uuid-1", "habit-uuid-2"]
}

Habit Analytics

Get Habit Statistics

GET /api/habits/{habit_id}/stats

Query Parameters:

  • period: week/month/year (default: month)
  • start_date: ISO 8601 date
  • end_date: ISO 8601 date

Response:

{
  "data": {
    "habit_id": "habit-uuid",
    "period": "month",
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "total_completions": 28,
    "total_days": 31,
    "completion_rate": 0.9032,
    "current_streak": 15,
    "longest_streak": 20,
    "average_completions_per_day": 1.2,
    "daily_breakdown": [
      {
        "date": "2024-01-01",
        "completions": 1,
        "target_met": true
      }
    ]
  }
}

Get Habit Calendar

GET /api/habits/calendar

Query Parameters:

  • start_date: ISO 8601 date
  • end_date: ISO 8601 date
  • habit_ids: Comma-separated list of habit IDs

Response:

{
  "data": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "habits": [
      {
        "habit_id": "habit-uuid",
        "name": "Take vitamins",
        "calendar_data": [
          {
            "date": "2024-01-01",
            "completions": 1,
            "target_met": true,
            "status": "completed"
          }
        ]
      }
    ]
  }
}

Get Dashboard

GET /api/habits/dashboard

Response:

{
  "data": {
    "overview": {
      "total_habits": 5,
      "active_habits": 4,
      "completed_today": 3,
      "completion_rate_today": 0.75,
      "current_streak_avg": 12.5
    },
    "habits": [
      {
        "habit_id": "habit-uuid",
        "name": "Take vitamins",
        "frequency_type": "daily",
        "completed_today": true,
        "completions_today": 1,
        "target_count": 1,
        "current_streak": 15,
        "status": "completed"
      }
    ],
    "upcoming": [
      {
        "habit_id": "habit-uuid",
        "name": "Weekly cleaning",
        "next_due_date": "2024-01-20",
        "days_until_due": 3
      }
    ]
  }
}

Intake Tracker API

Intake Metrics

List Intake Metrics

GET /api/intake/metrics

Query Parameters:

  • active: Filter by active status (true/false)
  • is_cumulative: Filter by cumulative type (true/false)
  • fields: Select specific fields

Response:

{
  "data": [
    {
      "id": "metric-uuid",
      "metric_type": "water",
      "unit": "ml",
      "display_name": "Water Intake",
      "target_value": 2000,
      "min_value": null,
      "max_value": null,
      "is_cumulative": true,
      "active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "total": 3,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Get Intake Metric

GET /api/intake/metrics/{metric_id}

Create Intake Metric

POST /api/intake/metrics

Request Body:

{
  "metric_type": "water",
  "unit": "ml",
  "display_name": "Water Intake",
  "target_value": 2000,
  "is_cumulative": true
}

Update Intake Metric

PUT /api/intake/metrics/{metric_id}

Delete Intake Metric

DELETE /api/intake/metrics/{metric_id}

Intake Records

List Intake Records

GET /api/intake/metrics/{metric_id}/records

Query Parameters:

  • start_date: ISO 8601 date
  • end_date: ISO 8601 date
  • limit, offset: Pagination

Response:

{
  "data": [
    {
      "id": "record-uuid",
      "intake_metric_id": "metric-uuid",
      "value": 500,
      "recorded_at": "2024-01-15T08:30:00Z",
      "notes": "Morning hydration",
      "created_at": "2024-01-15T08:30:00Z"
    }
  ],
  "meta": {
    "total": 8,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Create Intake Record

POST /api/intake/metrics/{metric_id}/records

Request Body:

{
  "value": 500,
  "recorded_at": "2024-01-15T08:30:00Z",
  "notes": "Morning hydration"
}

Bulk Create Records

POST /api/intake/records/bulk

Request Body:

{
  "records": [
    {
      "intake_metric_id": "metric-uuid-1",
      "value": 500,
      "recorded_at": "2024-01-15T08:30:00Z",
      "notes": "Morning water"
    },
    {
      "intake_metric_id": "metric-uuid-2",
      "value": 70.5,
      "recorded_at": "2024-01-15T07:00:00Z"
    }
  ]
}

Intake Progress

Get Metric Progress

GET /api/intake/metrics/{metric_id}/progress

Query Parameters:

  • date: Specific date (default: today)

Response:

{
  "data": {
    "metric_id": "metric-uuid",
    "date": "2024-01-15",
    "current_value": 1500,
    "target_value": 2000,
    "unit": "ml",
    "percentage_complete": 75,
    "status": "in_progress",
    "remaining": 500,
    "entries_count": 3,
    "first_entry_at": "2024-01-15T07:00:00Z",
    "last_entry_at": "2024-01-15T14:30:00Z"
  }
}

Get All Metrics Progress

GET /api/intake/progress

Response:

{
  "data": [
    {
      "metric_id": "metric-uuid",
      "metric_type": "water",
      "display_name": "Water Intake",
      "current_value": 1500,
      "target_value": 2000,
      "unit": "ml",
      "percentage_complete": 75,
      "status": "in_progress"
    }
  ]
}

Intake Analytics

Get Daily Summaries

GET /api/intake/metrics/{metric_id}/summaries

Query Parameters:

  • start_date: ISO 8601 date
  • end_date: ISO 8601 date
  • period: day/week/month (default: day)

Response:

{
  "data": [
    {
      "id": "summary-uuid",
      "intake_metric_id": "metric-uuid",
      "date": "2024-01-15",
      "total_value": 2100,
      "entry_count": 4,
      "first_entry_at": "2024-01-15T07:00:00Z",
      "last_entry_at": "2024-01-15T20:00:00Z",
      "target_met": true,
      "target_value": 2000
    }
  ]
}

Get Intake Trends

GET /api/intake/metrics/{metric_id}/trends

Query Parameters:

  • period: week/month/year (default: month)
  • start_date: ISO 8601 date
  • end_date: ISO 8601 date

Response:

{
  "data": {
    "metric_id": "metric-uuid",
    "period": "month",
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "average_daily_value": 1850,
    "target_value": 2000,
    "target_achievement_rate": 0.85,
    "highest_value": 2500,
    "lowest_value": 1200,
    "total_entries": 124,
    "daily_data": [
      {
        "date": "2024-01-01",
        "value": 1800,
        "target_met": false,
        "entry_count": 4
      }
    ]
  }
}

Get Intake Calendar

GET /api/intake/calendar

Query Parameters:

  • start_date: ISO 8601 date
  • end_date: ISO 8601 date
  • metric_ids: Comma-separated list of metric IDs

Response:

{
  "data": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "metrics": [
      {
        "metric_id": "metric-uuid",
        "display_name": "Water Intake",
        "unit": "ml",
        "calendar_data": [
          {
            "date": "2024-01-01",
            "value": 1800,
            "target_value": 2000,
            "target_met": false,
            "entry_count": 4
          }
        ]
      }
    ]
  }
}

Get Dashboard

GET /api/intake/dashboard

Response:

{
  "data": {
    "overview": {
      "total_metrics": 3,
      "active_metrics": 3,
      "targets_met_today": 2,
      "target_achievement_rate": 0.67
    },
    "metrics": [
      {
        "metric_id": "metric-uuid",
        "display_name": "Water Intake",
        "current_value": 1500,
        "target_value": 2000,
        "unit": "ml",
        "percentage_complete": 75,
        "status": "in_progress",
        "entries_today": 3
      }
    ]
  }
}

Cross-System Integration

Unified Dashboard

GET /api/dashboard

Response:

{
  "data": {
    "overview": {
      "date": "2024-01-15",
      "habits_completed": 3,
      "habits_total": 4,
      "intake_targets_met": 2,
      "intake_targets_total": 3
    },
    "habits": {
      "completed_today": 3,
      "completion_rate": 0.75,
      "current_streak_avg": 12.5,
      "habits": [
        {
          "habit_id": "habit-uuid",
          "name": "Take vitamins",
          "status": "completed",
          "completions_today": 1,
          "target_count": 1
        }
      ]
    },
    "intake": {
      "targets_met": 2,
      "target_achievement_rate": 0.67,
      "metrics": [
        {
          "metric_id": "metric-uuid",
          "display_name": "Water Intake",
          "current_value": 1500,
          "target_value": 2000,
          "status": "in_progress"
        }
      ]
    }
  }
}

Goal Integration

List Goal-Linked Habits

GET /api/goals/habits

Response:

{
  "data": [
    {
      "habit_id": "habit-uuid",
      "name": "Drink enough water",
      "goal_type": "water",
      "goal_target": 2000,
      "goal_unit": "ml",
      "linked_metric_id": "metric-uuid",
      "auto_complete": true,
      "status": "pending"
    }
  ]
}

Get Goal Status

GET /api/goals/status

Response:

{
  "data": [
    {
      "habit_id": "habit-uuid",
      "name": "Drink enough water",
      "goal_target": 2000,
      "current_intake": 1500,
      "goal_progress": 0.75,
      "goal_met": false,
      "habit_completed": false,
      "can_auto_complete": false
    }
  ]
}

Reports

Weekly Report

GET /api/reports/weekly

Query Parameters:

  • start_date: ISO 8601 date (default: start of current week)

Response:

{
  "data": {
    "period": "week",
    "start_date": "2024-01-08",
    "end_date": "2024-01-14",
    "habits": {
      "total_habits": 4,
      "average_completion_rate": 0.82,
      "best_habit": {
        "name": "Take vitamins",
        "completion_rate": 1.0
      },
      "needs_attention": [
        {
          "name": "Exercise",
          "completion_rate": 0.57
        }
      ]
    },
    "intake": {
      "total_metrics": 3,
      "average_target_achievement": 0.75,
      "best_metric": {
        "display_name": "Water Intake",
        "achievement_rate": 0.86
      }
    }
  }
}

Monthly Report

GET /api/reports/monthly

Real-Time Features

WebSocket Connection

Connect to WebSocket

wss://api.personal-system.com/v1/ws?token=<jwt_token>

WebSocket Events

Subscribe to Events

{
  "type": "subscribe",
  "channels": ["habits", "intake", "dashboard"]
}

Habit Completion Event

{
  "type": "habit_completed",
  "data": {
    "habit_id": "habit-uuid",
    "completion_id": "completion-uuid",
    "completed_at": "2024-01-15T08:30:00Z"
  }
}

Intake Record Event

{
  "type": "intake_recorded",
  "data": {
    "metric_id": "metric-uuid",
    "record_id": "record-uuid",
    "value": 500,
    "recorded_at": "2024-01-15T08:30:00Z"
  }
}

Goal Achievement Event

{
  "type": "goal_achieved",
  "data": {
    "habit_id": "habit-uuid",
    "metric_id": "metric-uuid",
    "goal_target": 2000,
    "current_value": 2000,
    "auto_completed": true
  }
}

Push Notifications

Register Device Token

POST /api/notifications/devices

Request Body:

{
  "token": "device_token_here",
  "platform": "ios",
  "app_version": "1.0.0"
}

Update Notification Settings

PUT /api/notifications/settings

Request Body:

{
  "habit_reminders": true,
  "goal_achievements": true,
  "daily_summary": true,
  "weekly_report": true
}

Client-Specific Optimizations

TUI Client

Compact Endpoints

Use the compact=true query parameter for minimal data transfer:

GET /api/habits/status?compact=true

Response:

{
  "data": [
    {
      "id": "habit-uuid",
      "name": "Take vitamins",
      "status": "completed"
    }
  ]
}

Terminal-Friendly Format

Use the format=terminal query parameter for structured output:

GET /api/habits/dashboard?format=terminal

Mobile Client

Offline Sync

GET /api/sync/changes?since=<timestamp>

Response:

{
  "data": {
    "habits": {
      "created": [],
      "updated": [],
      "deleted": []
    },
    "completions": {
      "created": [],
      "updated": [],
      "deleted": []
    },
    "intake_records": {
      "created": [],
      "updated": [],
      "deleted": []
    }
  },
  "sync_timestamp": "2024-01-15T12:00:00Z"
}

Quick Actions

POST /api/quick/habit-complete/{habit_id}

POST /api/quick/intake-record/{metric_id}

Web Client

Bulk Operations

POST /api/bulk/operations

Request Body:

{
  "operations": [
    {
      "type": "habit_complete",
      "habit_id": "habit-uuid"
    },
    {
      "type": "intake_record",
      "metric_id": "metric-uuid",
      "value": 500
    }
  ]
}

Export Data

GET /api/export/habits?format=csv&start_date=2024-01-01&end_date=2024-01-31

GET /api/export/intake?format=json&metric_ids=metric-uuid-1,metric-uuid-2

SDK and Integration

Webhook Support

Register Webhook

POST /api/webhooks

Request Body:

{
  "url": "https://your-app.com/webhook",
  "events": ["habit_completed", "goal_achieved"],
  "secret": "webhook_secret"
}

Webhook Payload

{
  "event": "habit_completed",
  "data": {
    "habit_id": "habit-uuid",
    "completion_id": "completion-uuid",
    "completed_at": "2024-01-15T08:30:00Z"
  },
  "timestamp": "2024-01-15T08:30:00Z",
  "signature": "sha256=..."
}

API Versioning

The API uses URL-based versioning:

  • Current version: /v1/
  • Future versions: /v2/, /v3/, etc.

Version deprecation notices will be provided via the X-API-Version-Deprecated header.

This API documentation provides comprehensive coverage of all endpoints for the personal productivity system, optimized for TUI, mobile, and web clients.