Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
364 lines (299 loc) · 11 KB

API_DOCUMENTATION.md

File metadata and controls

364 lines (299 loc) · 11 KB
Raw

🔌 HelloMed API Documentation

HelloMed primarily uses standard server-side rendering (SSR) via Laravel Blade templates. However, highly interactive features, such as the AI Health Assistant, rely on robust RESTful JSON API endpoints.

Table of Contents

🤖 AI Health Assistant APIs

The AI chat widget communicates with the Laravel backend via the following JSON endpoints. The backend then orchestrates communication with the locally hosted Ollama instance.

1. Send Chat Message

Endpoint: POST /api/ai/chat
Description: Processes a patient's natural language message, performs RAG (Retrieval-Augmented Generation) against hospital data, and returns a structured AI response containing text, doctor suggestions, and workflow navigation links.

Request Headers

  • Content-Type: application/json
  • Accept: application/json
  • X-CSRF-TOKEN: (Required for CSRF protection)

Request Body

{
  "message": "I have severe chest pain",
  "history": [
    {"role": "user", "content": "Hi"},
    {"role": "assistant", "content": "Hello! How can I help you today?"}
  ]
}

Parameters:

  • message (string, required, max: 1000) — The current message from the user.
  • history (array, optional, max: 12) — The previous conversation context to maintain memory.

Success Response (200 OK)

{
  "message": "I'm sorry to hear that. Since chest pain can be serious, please seek immediate help...",
  "intent": "health",
  "urgency": "high",
  "doctors": [
    {
      "id": 4,
      "name": "Dr. Mahmud Hasan",
      "specialty": "Cardiology",
      "photo_url": "/storage/doctors/mahmud.jpg"
    }
  ],
  "articles": [],
  "tests": [],
  "navigation_steps": [],
  "follow_up": "Would you like me to connect you with Dr. Mahmud Hasan?"
}

2. Check AI Status

Endpoint: GET /api/ai/chat/status
Description: Health check to verify if the local Ollama instance is running and if the configured LLM model is downloaded and available. The frontend uses this to gracefully hide the chat widget if the AI server is offline.

Success Response (200 OK)

{
  "available": true,
  "model": "mistral",
  "models": ["mistral", "phi3:mini"],
  "host": "http://localhost:11434"
}

3. Submit Chat Feedback

Endpoint: POST /api/ai/chat/feedback
Description: Allows patients to rate AI responses (thumbs up/down) to help administrators improve the system prompt and context matching algorithms over time.

Request Body

{
  "session_id": "sess_12345abcde",
  "rating": "helpful",
  "comment": "It gave me the exact doctor I needed!"
}

Parameters:

  • session_id (string, required, max: 64) — Unique identifier for the chat session.
  • rating (string, required) — Must be exactly helpful or not_helpful.
  • comment (string, optional, max: 500) — Additional qualitative feedback.

Success Response (200 OK)

{
  "success": true
}

📅 Doctor Scheduling APIs

Used to dynamically load and display a doctor's availability and booked slots on their public profile for appointment booking.

1. Get Doctor Schedule

Endpoint: GET /api/doctors/{doctor}/schedule (or equivalent web route)
Description: Returns the doctor's configured online/offline availability hours, slot durations, and an array of their currently booked/unavailable upcoming slots (next 14 days).

Success Response (200 OK)

{
  "online_available": true,
  "online_days": ["Monday", "Wednesday", "Friday"],
  "online_from": "09:00",
  "online_to": "14:00",
  "offline_available": true,
  "slot_minutes": 30,
  "booked_slots": [
    {
      "start": "2026-06-21 09:30:00",
      "start_formatted": "Jun 21, 2026 09:30 AM",
      "end_formatted": "10:00 AM"
    }
  ]
}

💬 Appointment Chat APIs

Used within the secured patient and doctor appointment panels to facilitate real-time messaging and file sharing.

1. Load Chat Messages

Endpoint: GET /my/appointments/{appointment}/chat (or equivalent web route)
Description: Returns all messages for a confirmed appointment. Access is strictly authorized only to the specific patient and the assigned doctor.

Success Response (200 OK)

{
  "enabled": true,
  "messages": [
    {
      "id": 1,
      "sender_id": 15,
      "sender_name": "John Doe",
      "is_mine": true,
      "message": "Here is my past medical report.",
      "created_at": "Jun 20, 2026 10:15 AM",
      "read_at": "Jun 20, 2026 10:16 AM",
      "attachment_url": "http://127.0.0.1:8000/storage/appointment-chat-attachments/report.pdf",
      "attachment_name": "report.pdf"
    }
  ]
}

2. Mark Messages as Read

Endpoint: POST /my/appointments/{appointment}/chat/read
Description: Marks all unread messages sent by the other party as read. Returns the count of messages updated.

Success Response (200 OK)

{
  "updated": 2
}

🔔 Notification Polling APIs

Used by the top navigation bar to periodically poll for unread notifications and update the notification drawer.

1. Fetch Notifications

Endpoint: GET /api/notifications (or equivalent web route)
Description: Returns the authenticated user's unread notification count and their 10 most recent notifications (both read and unread).

Success Response (200 OK)

{
  "unread_count": 3,
  "notifications": [
    {
      "id": "uuid-string",
      "data": {
        "title": "New Appointment",
        "message": "You have a new booking from John Doe.",
        "severity": "important",
        "action_url": "http://127.0.0.1:8000/doctor/appointments/45"
      },
      "read_at": null,
      "created_at": "2026-06-20T14:10:00.000000Z"
    }
  ]
}

2. Mark Notification as Read

Endpoint: POST /api/notifications/{id}/read
Description: Marks a single specific notification as read.

3. Mark All as Read

Endpoint: POST /api/notifications/read-all
Description: Marks all unread notifications for the user as read.

💊 Medicine APIs

Used by the frontend to dynamically search and fetch medicine suggestions.

1. Search Medicines

Endpoint: GET /api/medicines/search
Description: Performs a search on medicines based on name or group, returning a truncated list of suggestions. Useful for typeahead dropdowns and prescription building.

Request Parameters (Query String)

  • search (string, required) — The search term.

Success Response (200 OK)

[
  {
    "id": 1,
    "name": "Napa Extend",
    "power": "665 mg",
    "amount": "10.00",
    "stock": 50,
    "group": "Paracetamol"
  }
]

🛒 Shopping Cart APIs

Used by the frontend to asynchronously add, update, and remove medicines from the shopping cart without reloading the page.

1. Add to Cart

Endpoint: POST /api/cart
Description: Adds a specified quantity of a medicine to the user's session-based cart.

Request Body

{
  "medicine_id": 42,
  "quantity": 2
}

Success Response (200 OK)

{
  "success": true,
  "message": "Added to cart",
  "item_count": 5
}

2. Update Cart Item

Endpoint: PATCH /api/cart/{medicine}
Description: Updates the quantity of a specific medicine in the cart.

Request Body

{
  "quantity": 3
}

Success Response (200 OK)

{
  "success": true,
  "message": "Cart updated",
  "item_count": 6
}

3. Remove Cart Item

Endpoint: DELETE /api/cart/{medicine}
Description: Removes a medicine entirely from the cart.

Success Response (200 OK)

{
  "success": true,
  "message": "Item removed",
  "item_count": 3
}

🗺️ Disease Outbreak APIs

Used by the frontend Disease Map (/disease-map) to visualize real-time epidemiological data across Bangladesh's 64 districts.

1. Fetch Disease Data

Endpoint: GET /api/disease-outbreak
Description: Fetches country-level disease case counts from the WHO Global Health Observatory (GHO) API or Johns Hopkins (disease.sh), and models the district-level distribution using population density weighting. Caches results for 6 hours.

Request Parameters (Query String)

  • disease (string, optional, default: dengue) — The disease identifier. Valid options: dengue, cholera, tuberculosis, malaria, typhoid, covid19.

Success Response (200 OK)

{
  "disease": "covid19",
  "label": "COVID-19",
  "icon": "🦠",
  "color": "#f97316",
  "description": "COVID-19 cases in the last 365 days",
  "unit": "cases",
  "total": 89073,
  "districts": [
    {
      "district": "Dhaka",
      "division": "Dhaka",
      "cases": 14608,
      "share": 16.4,
      "intensity": 1,
      "severity": "critical"
    }
  ],
  "source": "Johns Hopkins University (via disease.sh)",
  "year": "2026",
  "updated_at": "2026-07-13 04:37:50"
}

🔑 Google OAuth & Integration

Used to authenticate users and securely link their Google Accounts for Google Calendar sync capabilities.

1. Redirect to Google Auth

Endpoint: GET /auth/google
Description: Redirects the user to the Google OAuth consent screen to request calendar.events scope and offline access for the refresh token.

2. Google Auth Callback

Endpoint: GET /auth/google/callback
Description: The callback URL where Google sends the authorization code. The backend exchanges the code for a token and refresh token, linking the Google account to the logged-in user, or automatically logging in/registering a new patient account based on their email.

3. Unlink Google Account

Endpoint: DELETE /auth/google/unlink
Description: Detaches the Google Account tokens and email from the authenticated user, completely disabling Google Calendar sync and email notifications.

🔒 Security & Authentication

  • Session-Based: All API routes currently rely on Laravel's built-in session authentication (web middleware group) to maintain authentication state seamlessly between the standard web application and API endpoints.
  • CSRF Protection: Every POST/PUT/DELETE request must include the X-CSRF-TOKEN header. This is automatically handled by the globally configured Axios wrapper reading the <meta name="csrf-token"> tag.
  • JSON Enforcement: The API uses a custom ForceJsonResponse middleware applied to all routes in routes/api.php, which guarantees that errors (validation, unauthenticated, unauthorized) return standard JSON responses rather than HTML redirects.
  • Rate Limiting: Usage is throttled (e.g., throttle:60,1 or throttle:api) to prevent abuse.