backend-service/docs/API.md

Attune Heart Therapy API Documentation

Overview

The Attune Heart Therapy API is a comprehensive video conference booking system that enables users to schedule therapy sessions, process payments, and manage appointments. The API provides endpoints for user authentication, booking management, payment processing, and administrative functions.

Base URL: http://localhost:8080
API Version: v1
Authentication: JWT Bearer Token

Table of Contents

1. Authentication Flow
2. API Usage Flow
3. Endpoints
4. Data Models
5. Error Handling
6. Rate Limiting

Authentication Flow

The API uses JWT (JSON Web Token) for authentication. Here's the authentication flow:

1. Register a new user account or Login with existing credentials
2. Receive a JWT token in the response
3. Include the token in the Authorization header for protected endpoints: Bearer <token>
4. Token expires after 24 hours (configurable)

Authentication Headers

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

API Usage Flow

For Regular Users (Clients)

graph TD
    A[Register/Login] --> B[Get Available Slots]
    B --> C[Create Booking]
    C --> D[Create Payment Intent]
    D --> E[Confirm Payment]
    E --> F[Receive Jitsi Room Details]
    F --> G[Join Video Session]
    
    C --> H[View My Bookings]
    H --> I[Cancel/Reschedule Booking]

For Administrators

graph TD
    A[Admin Login] --> B[View Dashboard]
    B --> C[Create Schedule Slots]
    C --> D[Manage Users]
    D --> E[View All Bookings]
    E --> F[Generate Reports]

Typical User Journey

1. User Registration/Login

   • New users register with personal details
   • Existing users login with email/password
   • System returns JWT token for subsequent requests

2. Browse Available Slots

   • User queries available time slots for specific dates
   • System returns available schedule slots

3. Create Booking

   • User selects a time slot and creates a booking
   • System reserves the slot and returns booking details

4. Payment Processing

   • User initiates payment through Stripe integration
   • System creates payment intent and processes payment
   • Upon successful payment, booking is confirmed

5. Session Management

   • System generates Jitsi room details
   • User receives video conference link
   • User can view, cancel, or reschedule bookings

Endpoints

Health & Monitoring

GET /health

Basic health check endpoint.

Response:

{
  "status": "ok",
  "message": "Video Conference Booking System API",
  "timestamp": "2024-12-06T10:00:00Z"
}

GET /health/detailed

Detailed system health check.

Response:

{
  "status": "healthy",
  "checks": {
    "database": "healthy",
    "job_manager": "healthy",
    "memory": "healthy"
  },
  "timestamp": "2024-12-06T10:00:00Z"
}

GET /metrics

System metrics and monitoring data.

Authentication Endpoints

POST /api/auth/register

Register a new user account.

Request Body:

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "location": "New York, NY",
  "password": "securepassword123"
}

Response (201):

{
  "message": "User registered successfully",
  "user": {
    "id": 1,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "location": "New York, NY",
    "is_admin": false,
    "created_at": "2024-12-06T10:00:00Z"
  }
}

POST /api/auth/login

Authenticate user and receive JWT token.

Request Body:

{
  "email": "john.doe@example.com",
  "password": "securepassword123"
}

Response (200):

{
  "message": "Login successful",
  "user": {
    "id": 1,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "is_admin": false
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

GET /api/auth/profile

Get current user profile (requires authentication).

Headers: Authorization: Bearer <token>

Response (200):

{
  "user": {
    "id": 1,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "location": "New York, NY",
    "is_admin": false
  }
}

PUT /api/auth/profile

Update user profile (requires authentication).

Headers: Authorization: Bearer <token>

Request Body:

{
  "first_name": "John",
  "last_name": "Smith",
  "phone": "+1234567891",
  "location": "Los Angeles, CA"
}

POST /api/auth/logout

Logout user (requires authentication).

Headers: Authorization: Bearer <token>

Schedule & Booking Endpoints

GET /api/schedules

Get available time slots for a specific date.

Query Parameters:

• date (required): Date in YYYY-MM-DD format

Example: /api/schedules?date=2024-12-15

Response (200):

{
  "date": "2024-12-15",
  "slots": [
    {
      "id": 1,
      "start_time": "2024-12-15T10:00:00Z",
      "end_time": "2024-12-15T11:00:00Z",
      "is_available": true,
      "max_bookings": 1,
      "booked_count": 0,
      "remaining_slots": 1
    }
  ]
}

POST /api/bookings

Create a new booking (requires authentication).

Headers: Authorization: Bearer <token>

Request Body:

{
  "schedule_id": 1,
  "duration": 60,
  "notes": "Initial consultation session"
}

Response (201):

{
  "message": "Booking created successfully",
  "booking": {
    "id": 1,
    "user_id": 1,
    "scheduled_at": "2024-12-15T10:00:00Z",
    "duration": 60,
    "status": "scheduled",
    "jitsi_room_id": "room_abc123",
    "jitsi_room_url": "https://meet.jit.si/room_abc123",
    "amount": 100.00,
    "payment_status": "pending",
    "notes": "Initial consultation session"
  }
}

GET /api/bookings

Get all bookings for the current user (requires authentication).

Headers: Authorization: Bearer <token>

Response (200):

{
  "bookings": [
    {
      "id": 1,
      "scheduled_at": "2024-12-15T10:00:00Z",
      "duration": 60,
      "status": "scheduled",
      "jitsi_room_url": "https://meet.jit.si/room_abc123",
      "amount": 100.00,
      "payment_status": "succeeded"
    }
  ]
}

PUT /api/bookings/:id/cancel

Cancel a booking (requires authentication).

Headers: Authorization: Bearer <token>

Requirements: Booking must be at least 24 hours before scheduled time.

Response (200):

{
  "message": "Booking cancelled successfully"
}

PUT /api/bookings/:id/reschedule

Reschedule a booking to a new time slot (requires authentication).

Headers: Authorization: Bearer <token>

Request Body:

{
  "new_schedule_id": 2
}

Requirements: Booking must be at least 2 hours before scheduled time.

Payment Endpoints

POST /api/payments/intent

Create a payment intent for Stripe (requires authentication).

Headers: Authorization: Bearer <token>

Request Body:

{
  "amount": 10000,
  "currency": "usd"
}

Note: Amount is in cents (10000 = $100.00)

Response (201):

{
  "message": "Payment intent created successfully",
  "client_secret": "pi_1234567890_secret_abc123",
  "payment_intent": "pi_1234567890",
  "amount": 10000,
  "currency": "usd",
  "status": "requires_payment_method"
}

POST /api/payments/confirm

Confirm a payment intent (requires authentication).

Headers: Authorization: Bearer <token>

Request Body:

{
  "payment_intent_id": "pi_1234567890"
}

Response (200):

{
  "message": "Payment confirmed successfully",
  "payment_intent": "pi_1234567890",
  "status": "succeeded",
  "amount": 10000,
  "currency": "usd"
}

POST /api/payments/webhook

Stripe webhook endpoint (no authentication required).

Headers:

• Content-Type: application/json
• Stripe-Signature: <stripe_signature>

Admin Endpoints

All admin endpoints require authentication with admin privileges.

GET /api/admin/dashboard

Get dashboard statistics (admin only).

Headers: Authorization: Bearer <admin_token>

Response (200):

{
  "stats": {
    "total_users": 150,
    "total_bookings": 89,
    "pending_bookings": 12,
    "completed_bookings": 67,
    "cancelled_bookings": 10,
    "total_revenue": 8900.00,
    "monthly_revenue": 2100.00
  }
}

POST /api/admin/schedules

Create a new schedule slot (admin only).

Headers: Authorization: Bearer <admin_token>

Request Body:

{
  "start_time": "2024-12-15T10:00:00Z",
  "end_time": "2024-12-15T11:00:00Z",
  "max_bookings": 1,
  "is_available": true
}

PUT /api/admin/schedules/:id

Update an existing schedule slot (admin only).

GET /api/admin/users

Get all users with pagination (admin only).

Query Parameters:

• limit (optional): Number of users to return (default: 50)
• offset (optional): Number of users to skip (default: 0)

GET /api/admin/bookings

Get all bookings with pagination (admin only).

GET /api/admin/reports/financial

Get financial reports for a date range (admin only).

Query Parameters:

• start_date (required): Start date in YYYY-MM-DD format
• end_date (required): End date in YYYY-MM-DD format

Data Models

User

{
  "id": 1,
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "location": "New York, NY",
  "date_of_birth": "1990-01-01T00:00:00Z",
  "is_admin": false,
  "created_at": "2024-12-06T10:00:00Z",
  "updated_at": "2024-12-06T10:00:00Z"
}

Booking

{
  "id": 1,
  "user_id": 1,
  "scheduled_at": "2024-12-15T10:00:00Z",
  "duration": 60,
  "status": "scheduled",
  "jitsi_room_id": "room_abc123",
  "jitsi_room_url": "https://meet.jit.si/room_abc123",
  "payment_id": "pi_1234567890",
  "payment_status": "succeeded",
  "amount": 100.00,
  "notes": "Initial consultation session",
  "created_at": "2024-12-06T10:00:00Z",
  "updated_at": "2024-12-06T10:00:00Z"
}

Schedule

{
  "id": 1,
  "start_time": "2024-12-15T10:00:00Z",
  "end_time": "2024-12-15T11:00:00Z",
  "is_available": true,
  "max_bookings": 1,
  "booked_count": 0,
  "created_at": "2024-12-06T10:00:00Z",
  "updated_at": "2024-12-06T10:00:00Z"
}

Status Codes

Booking Status

• scheduled: Booking is confirmed and scheduled
• completed: Session has been completed
• cancelled: Booking has been cancelled

Payment Status

• pending: Payment is pending
• succeeded: Payment was successful
• failed: Payment failed
• refunded: Payment was refunded

Error Handling

The API returns standard HTTP status codes and error messages in JSON format.

Error Response Format

{
  "error": "Error message",
  "details": "Detailed error information"
}

Common HTTP Status Codes

• 200 OK: Request successful
• 201 Created: Resource created successfully
• 400 Bad Request: Invalid request format or parameters
• 401 Unauthorized: Authentication required or invalid token
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource not found
• 409 Conflict: Resource conflict (e.g., time slot already booked)
• 422 Payment Required: Payment failed or required
• 500 Internal Server Error: Server error

Common Error Scenarios

Authentication Errors

{
  "error": "User not authenticated"
}

Validation Errors

{
  "error": "Invalid request format",
  "details": "Email is required"
}

Business Logic Errors

{
  "error": "The selected time slot is no longer available"
}

Rate Limiting

The API implements rate limiting to prevent abuse:

• General endpoints: 100 requests per minute per IP
• Authentication endpoints: 5 requests per minute per IP (strict rate limiting)
• Admin endpoints: 200 requests per minute per authenticated admin

Rate limit headers are included in responses:

• X-RateLimit-Limit: Request limit per window
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Time when the rate limit resets

Security Features

• JWT Authentication: Secure token-based authentication
• Password Hashing: Bcrypt hashing for user passwords
• CORS Protection: Cross-origin request protection
• Rate Limiting: Protection against abuse and DDoS
• Input Validation: Comprehensive request validation
• SQL Injection Protection: Parameterized queries with GORM
• Security Headers: Standard security headers included

Integration Examples

Frontend Integration (JavaScript)

// Login and store token
const loginResponse = await fetch('/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
});

const { token } = await loginResponse.json();
localStorage.setItem('authToken', token);

// Make authenticated request
const bookingsResponse = await fetch('/api/bookings', {
  headers: {
    'Authorization': `Bearer ${localStorage.getItem('authToken')}`
  }
});

cURL Examples

# Register user
curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "password": "password123"
  }'

# Login
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "password": "password123"
  }'

# Get available slots
curl -X GET "http://localhost:8080/api/schedules?date=2024-12-15"

# Create booking (with auth token)
curl -X POST http://localhost:8080/api/bookings \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule_id": 1,
    "duration": 60,
    "notes": "Initial consultation"
  }'

Support

For API support and questions, please contact the development team or refer to the project documentation.