Initial commit: Complete NodeJS-native setup
- Migrated from Python pre-commit to NodeJS-native solution - Reorganized documentation structure - Set up Husky + lint-staged for efficient pre-commit hooks - Fixed Dockerfile healthcheck issue - Added comprehensive documentation index
This commit is contained in:
William Valentin
839
docs/development/API.md
Normal file
839
docs/development/API.md
Normal file
@@ -0,0 +1,839 @@
|
||||
# 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
|
||||
|
||||
- [Postman Collection](./postman-collection.json)
|
||||
- [OpenAPI Specification](./openapi.yaml)
|
||||
- [SDK Documentation](./sdk-docs.md)
|
||||
- [Integration Examples](./examples/)
|
||||
Reference in New Issue
Block a user