rxminder/docs/development/API.md

# 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**

```http
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:**

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

**Response:**

```json
{
  "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

---

### **Login User**

Authenticate user with email and password.

**Endpoint:** `POST /auth/login`

**Request Body:**

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

**Response:**

```json
{
  "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

---

### **OAuth Login**

Authenticate using OAuth providers (Google, GitHub).

**Endpoint:** `POST /auth/oauth`

**Request Body:**

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

**Response:**

```json
{
  "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:**

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

**Response:**

```json
{
  "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:**

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

**Response:**

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

---

### **Request Password Reset**

Request password reset email.

**Endpoint:** `POST /auth/request-password-reset`

**Request Body:**

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

**Response:**

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

---

### **Reset Password**

Reset password using reset token.

**Endpoint:** `POST /auth/reset-password`

**Request Body:**

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

**Response:**

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

---

## 💊 Medication Management

### **Add Medication**

Add a new medication to user's list.

**Endpoint:** `POST /medications`

**Request Body:**

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

**Response:**

```json
{
  "_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:**

```json
[
  {
    "_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:**

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

**Response:**

```json
{
  "_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:**

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

---

## ⏰ Reminder Management

### **Add Custom Reminder**

Create a custom reminder.

**Endpoint:** `POST /reminders`

**Request Body:**

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

**Response:**

```json
{
  "_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:**

```json
[
  {
    "_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:**

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

**Response:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "status": "SUSPENDED"
}
```

**Response:**

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

---

### **Delete User**

Delete user account (admin only).

**Endpoint:** `DELETE /admin/users/:id`

**Response:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

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

**Response:**

```json
{
  "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:**

```json
{
  "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:**

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

---

## ❌ Error Responses

### **Error Format**

```json
{
  "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**

```http
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.md) - Database abstraction layer documentation
- [Application Security](APPLICATION_SECURITY.md) - Security practices and guidelines
- [Code Quality](CODE_QUALITY.md) - Development standards and best practices