Files

William Valentin 36dcdbd459 docs: fix broken references and update paths

- Update README.md to remove references to deleted migration/deployment docs
- Fix CONTRIBUTING.md to point to correct documentation paths
- Remove broken references in API.md to non-existent files
- Update ENVIRONMENT_VARIABLES.md to reference existing documentation
- Ensure all documentation links work correctly after reorganization

2025-09-08 21:38:07 -07:00

12 KiB

Raw Permalink Blame History

API Documentation

📚 API Reference for Medication Reminder App

Base URL

Development: http://localhost:5173
Production: http://localhost:8080

Authentication

All authenticated endpoints require a valid session token.

Headers

Authorization: Bearer <token>
Content-Type: application/json

🔐 Authentication Endpoints

Register User

Create a new user account with email verification.

Endpoint: POST /auth/register

Request Body:

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "username": "JohnDoe"
}

Response:

{
  "user": {
    "_id": "user-uuid",
    "email": "user@example.com",
    "username": "JohnDoe",
    "status": "PENDING",
    "emailVerified": false,
    "role": "USER",
    "createdAt": "2025-09-05T12:00:00Z"
  },
  "verificationToken": {
    "token": "verification-token-uuid",
    "expiresAt": "2025-09-05T13:00:00Z"
  }
}

Status Codes:

201 - User created successfully
400 - Invalid input data
409 - Email already exists

Authenticate user with email and password.

Endpoint: POST /auth/login

Request Body:

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

Response:

{
  "user": {
    "_id": "user-uuid",
    "email": "user@example.com",
    "username": "JohnDoe",
    "status": "ACTIVE",
    "emailVerified": true,
    "role": "USER"
  },
  "accessToken": "jwt-access-token",
  "refreshToken": "jwt-refresh-token"
}

Status Codes:

200 - Login successful
401 - Invalid credentials
403 - Account not verified or suspended

Authenticate using OAuth providers (Google, GitHub).

Endpoint: POST /auth/oauth

Request Body:

{
  "provider": "google",
  "userData": {
    "email": "user@example.com",
    "username": "John Doe",
    "avatar": "https://example.com/avatar.jpg"
  }
}

Response:

{
  "user": {
    "_id": "user-uuid",
    "email": "user@example.com",
    "username": "John Doe",
    "status": "ACTIVE",
    "emailVerified": true,
    "role": "USER",
    "avatar": "https://example.com/avatar.jpg"
  },
  "accessToken": "jwt-access-token",
  "refreshToken": "jwt-refresh-token"
}

Verify Email

Activate user account using verification token.

Endpoint: POST /auth/verify-email

Request Body:

{
  "token": "verification-token-uuid"
}

Response:

{
  "user": {
    "_id": "user-uuid",
    "email": "user@example.com",
    "username": "JohnDoe",
    "status": "ACTIVE",
    "emailVerified": true,
    "role": "USER"
  }
}

Change Password

Change user password (requires current password).

Endpoint: POST /auth/change-password

Request Body:

{
  "userId": "user-uuid",
  "currentPassword": "OldPassword123!",
  "newPassword": "NewPassword456!"
}

Response:

{
  "success": true,
  "message": "Password changed successfully"
}

Request Password Reset

Request password reset email.

Endpoint: POST /auth/request-password-reset

Request Body:

{
  "email": "user@example.com"
}

Response:

{
  "success": true,
  "message": "Password reset email sent"
}

Reset Password

Reset password using reset token.

Endpoint: POST /auth/reset-password

Request Body:

{
  "token": "reset-token-uuid",
  "newPassword": "NewPassword123!"
}

Response:

{
  "success": true,
  "message": "Password reset successful"
}

💊 Medication Management

Add Medication

Add a new medication to user's list.

Endpoint: POST /medications

Request Body:

{
  "name": "Aspirin",
  "dosage": "100mg",
  "frequency": "Daily",
  "startTime": "08:00",
  "notes": "Take with food",
  "icon": "💊"
}

Response:

{
  "_id": "medication-uuid",
  "name": "Aspirin",
  "dosage": "100mg",
  "frequency": "Daily",
  "startTime": "08:00",
  "notes": "Take with food",
  "icon": "💊",
  "userId": "user-uuid",
  "createdAt": "2025-09-05T12:00:00Z"
}

Get Medications

Retrieve user's medications.

Endpoint: GET /medications

Query Parameters:

active (boolean) - Filter active medications only

Response:

[
  {
    "_id": "medication-uuid",
    "name": "Aspirin",
    "dosage": "100mg",
    "frequency": "Daily",
    "startTime": "08:00",
    "notes": "Take with food",
    "icon": "💊"
  }
]

Update Medication

Update existing medication.

Endpoint: PUT /medications/:id

Request Body:

{
  "dosage": "200mg",
  "notes": "Take with plenty of water"
}

Response:

{
  "_id": "medication-uuid",
  "name": "Aspirin",
  "dosage": "200mg",
  "frequency": "Daily",
  "startTime": "08:00",
  "notes": "Take with plenty of water",
  "icon": "💊"
}

Delete Medication

Remove medication from user's list.

Endpoint: DELETE /medications/:id

Response:

{
  "success": true,
  "message": "Medication deleted successfully"
}

⏰ Reminder Management

Add Custom Reminder

Create a custom reminder.

Endpoint: POST /reminders

Request Body:

{
  "title": "Doctor Appointment",
  "message": "Annual checkup with Dr. Smith",
  "scheduledFor": "2025-09-15T14:00:00Z",
  "recurrence": "yearly"
}

Response:

{
  "_id": "reminder-uuid",
  "title": "Doctor Appointment",
  "message": "Annual checkup with Dr. Smith",
  "scheduledFor": "2025-09-15T14:00:00Z",
  "recurrence": "yearly",
  "userId": "user-uuid",
  "isActive": true
}

Get Reminders

Retrieve user's reminders.

Endpoint: GET /reminders

Query Parameters:

date (string) - Filter by specific date (YYYY-MM-DD)
active (boolean) - Filter active reminders only

Response:

[
  {
    "_id": "reminder-uuid",
    "title": "Doctor Appointment",
    "message": "Annual checkup with Dr. Smith",
    "scheduledFor": "2025-09-15T14:00:00Z",
    "recurrence": "yearly",
    "isActive": true
  }
]

📊 Dose Tracking

Record Taken Dose

Mark a dose as taken.

Endpoint: POST /doses/taken

Request Body:

{
  "medicationId": "medication-uuid",
  "scheduledTime": "2025-09-05T08:00:00Z",
  "takenAt": "2025-09-05T08:15:00Z",
  "notes": "Took with breakfast"
}

Response:

{
  "success": true,
  "dose": {
    "id": "medication-uuid-2025-09-05",
    "medicationId": "medication-uuid",
    "scheduledTime": "2025-09-05T08:00:00Z",
    "takenAt": "2025-09-05T08:15:00Z",
    "status": "TAKEN",
    "notes": "Took with breakfast"
  }
}

Get Dose History

Retrieve dose history for analytics.

Endpoint: GET /doses

Query Parameters:

medicationId (string) - Filter by medication
startDate (string) - Start date (YYYY-MM-DD)
endDate (string) - End date (YYYY-MM-DD)
status (string) - Filter by status (TAKEN, MISSED, UPCOMING)

Response:

{
  "doses": [
    {
      "id": "medication-uuid-2025-09-05",
      "medicationId": "medication-uuid",
      "scheduledTime": "2025-09-05T08:00:00Z",
      "takenAt": "2025-09-05T08:15:00Z",
      "status": "TAKEN"
    }
  ],
  "stats": {
    "totalDoses": 30,
    "takenDoses": 28,
    "missedDoses": 2,
    "adherenceRate": 93.3
  }
}

👑 Admin Endpoints

Get All Users

Retrieve all users (admin only).

Endpoint: GET /admin/users

Query Parameters:

status (string) - Filter by status
role (string) - Filter by role
page (number) - Pagination page
limit (number) - Items per page

Response:

{
  "users": [
    {
      "_id": "user-uuid",
      "email": "user@example.com",
      "username": "JohnDoe",
      "status": "ACTIVE",
      "role": "USER",
      "emailVerified": true,
      "createdAt": "2025-09-05T12:00:00Z",
      "lastLoginAt": "2025-09-05T15:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Update User Status

Change user account status (admin only).

Endpoint: PUT /admin/users/:id/status

Request Body:

{
  "status": "SUSPENDED"
}

Response:

{
  "success": true,
  "user": {
    "_id": "user-uuid",
    "status": "SUSPENDED"
  }
}

Delete User

Delete user account (admin only).

Endpoint: DELETE /admin/users/:id

Response:

{
  "success": true,
  "message": "User deleted successfully"
}

📈 Analytics

User Statistics

Get user's medication adherence statistics.

Endpoint: GET /analytics/stats

Query Parameters:

period (string) - Time period (7d, 30d, 90d, 1y)

Response:

{
  "adherence": {
    "overall": 92.5,
    "trend": "improving",
    "streak": 7
  },
  "medications": [
    {
      "medicationId": "medication-uuid",
      "name": "Aspirin",
      "taken": 28,
      "missed": 2,
      "adherence": 93.3
    }
  ],
  "dailyStats": [
    {
      "date": "2025-09-05",
      "adherence": 100,
      "totalDoses": 3,
      "takenDoses": 3
    }
  ]
}

🔧 User Settings

Get User Settings

Retrieve user preferences.

Endpoint: GET /settings

Response:

{
  "notifications": {
    "email": true,
    "push": false,
    "reminderSound": true
  },
  "preferences": {
    "theme": "dark",
    "timezone": "UTC-5",
    "dateFormat": "MM/DD/YYYY"
  },
  "privacy": {
    "shareStats": false,
    "anonymousUsage": true
  }
}

Update User Settings

Update user preferences.

Endpoint: PUT /settings

Request Body:

{
  "notifications": {
    "email": false,
    "push": true
  },
  "preferences": {
    "theme": "light"
  }
}

Response:

{
  "success": true,
  "settings": {
    "notifications": {
      "email": false,
      "push": true,
      "reminderSound": true
    },
    "preferences": {
      "theme": "light",
      "timezone": "UTC-5",
      "dateFormat": "MM/DD/YYYY"
    }
  }
}

📁 File Upload

Upload Avatar

Upload user avatar image.

Endpoint: POST /upload/avatar

Request: Multipart form data

avatar (file) - Image file (JPEG, PNG, max 2MB)

Response:

{
  "success": true,
  "avatarUrl": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
}

🔍 Search

Search Medications

Search for medications by name.

Endpoint: GET /search/medications

Query Parameters:

q (string) - Search query
limit (number) - Max results

Response:

{
  "results": [
    {
      "name": "Aspirin",
      "commonDosages": ["100mg", "325mg", "500mg"],
      "category": "Pain Reliever"
    }
  ]
}

❌ Error Responses

Error Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "email": "Invalid email format",
      "password": "Password too weak"
    }
  }
}

Common Error Codes

VALIDATION_ERROR (400) - Invalid input data
UNAUTHORIZED (401) - Authentication required
FORBIDDEN (403) - Insufficient permissions
NOT_FOUND (404) - Resource not found
CONFLICT (409) - Resource already exists
RATE_LIMITED (429) - Too many requests
INTERNAL_ERROR (500) - Server error

📊 Rate Limiting

Limits

Authentication endpoints: 5 requests/minute
General API: 100 requests/minute
Upload endpoints: 10 requests/minute

Headers

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

🔒 Security

Authentication

JWT tokens with 24-hour expiration
Refresh tokens for automatic renewal
Secure password hashing with bcrypt

Authorization

Role-based access control (USER, ADMIN)
Resource-level permissions
Account status validation

Data Protection

Input validation and sanitization
SQL injection prevention
XSS protection
CORS configuration

📚 Additional Resources

Database Service - Database abstraction layer documentation
Application Security - Security practices and guidelines
Code Quality - Development standards and best practices

12 KiB Raw Permalink Blame History

API Documentation

📚 API Reference for Medication Reminder App

Base URL

Authentication

Headers

🔐 Authentication Endpoints

Register User

Login User

OAuth Login

Verify Email

Change Password

Request Password Reset

Reset Password

💊 Medication Management

Add Medication

Get Medications

Update Medication

Delete Medication

⏰ Reminder Management

Add Custom Reminder

Get Reminders

📊 Dose Tracking

Record Taken Dose

Get Dose History

👑 Admin Endpoints

Get All Users

Update User Status

Delete User

📈 Analytics

User Statistics

🔧 User Settings

Get User Settings

Update User Settings

📁 File Upload

Upload Avatar

🔍 Search

Search Medications

❌ Error Responses

Error Format

Common Error Codes

📊 Rate Limiting

Limits

Headers

🔒 Security

Authentication

Authorization

Data Protection

📚 Additional Resources

12 KiB

Raw Permalink Blame History