📱 Mobile API Documentation¶

NewWaves Hospital Management System provides a comprehensive RESTful API for mobile applications, enabling patients and staff to access hospital services through mobile apps.

📋 API Overview¶

Base URL¶

https://your-domain.com/api/v1/

Authentication¶

The API uses Laravel Sanctum for token-based authentication: - Token Type: Bearer Token - Header: Authorization: Bearer {your-token} - Token Location: Include in request headers

Content Type¶

All requests should include:

Content-Type: application/json
Accept: application/json

Response Format¶

All API responses follow a consistent JSON format:

Success Response:

{
    "success": true,
    "message": "Operation completed successfully",
    "data": {
        // Response data here
    }
}

Error Response:

{
    "success": false,
    "message": "Error description",
    "errors": {
        // Validation errors (if applicable)
    }
}

🔐 Authentication Endpoints¶

Patient Registration¶

POST /auth/register/patient

Register a new patient account.

Request Body:

{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "password": "password123",
    "password_confirmation": "password123",
    "date_of_birth": "1990-01-01",
    "gender": "male",
    "address": "123 Main St, City, Country"
}

Response:

{
    "success": true,
    "message": "Patient registered successfully",
    "data": {
        "patient": {
            "id": 1,
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com",
            // ... other patient data
        },
        "token": "1|abcdef123456..."
    }
}

POST /auth/login/patient

Authenticate a patient and receive access token.

Request Body:

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

Response:

{
    "success": true,
    "message": "Login successful",
    "data": {
        "patient": {
            "id": 1,
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com"
        },
        "token": "1|abcdef123456...",
        "token_type": "Bearer"
    }
}

POST /auth/login/staff

Authenticate staff members (doctors, nurses, admin).

Request Body:

{
    "email": "doctor@hospital.com",
    "password": "password123",
    "role": "doctor" // optional: doctor, nurse, admin
}

Response:

{
    "success": true,
    "message": "Staff login successful",
    "data": {
        "user": {
            "id": 1,
            "name": "Dr. Smith",
            "email": "doctor@hospital.com",
            "role": "doctor"
        },
        "token": "2|xyz789...",
        "token_type": "Bearer"
    }
}

Logout¶

POST /auth/logout Requires Authentication

Revoke the current access token.

Response:

{
    "success": true,
    "message": "Successfully logged out"
}

Get Profile¶

GET /auth/profile Requires Authentication

Get current user profile information.

Response:

{
    "success": true,
    "data": {
        "user": {
            "id": 1,
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com",
            "phone": "+1234567890",
            // ... other profile data
        }
    }
}

Update Profile¶

PUT /auth/profile Requires Authentication

Update user profile information.

Request Body:

{
    "first_name": "John",
    "last_name": "Smith",
    "phone": "+1234567890",
    "address": "456 New St, City, Country"
}

Change Password¶

POST /auth/change-password Requires Authentication

Change user password.

Request Body:

{
    "current_password": "oldpassword",
    "new_password": "newpassword123",
    "new_password_confirmation": "newpassword123"
}

🏥 Public Information Endpoints¶

Get Departments¶

GET /public/departments

Retrieve all hospital departments.

Query Parameters: - search (optional): Search departments by name - active_only (optional): Filter active departments only

Response:

{
    "success": true,
    "data": {
        "departments": [
            {
                "id": 1,
                "name": "Cardiology",
                "description": "Heart and cardiovascular care",
                "image": "https://domain.com/uploads/cardiology.jpg",
                "is_active": true,
                "doctors_count": 5
            }
        ]
    }
}

Get Department Details¶

GET /public/departments/{id}

Get detailed information about a specific department.

Response:

href="#__codelineno-15-1">{ "success": true, "data": { "department": { "id": 1, "name": "Cardiology", "description": "Comprehensive heart care services...", "image": "https://domain.com/uploads/cardiology.jpg", "is_active": true, "services": ["ECG", "Echocardiogram", "Cardiac Surgery"], "doctors": [ { "id": 1, "name": "Dr. Smith", "specialization": "Cardiologist", "image": "doctor1.jpg" } ] } } }

Get Doctors¶

GET /public/doctors

Retrieve all hospital doctors.

Query Parameters: - search (optional): Search by doctor name - department_id (optional): Filter by department - specialization (optional): Filter by specialization

Response:

{
    "success": true,
    "data": {
        "doctors": [
            {
                "id": 1,
                "name": "Dr. John Smith",
                "specialization": "Cardiologist",
                "department": "Cardiology",
                "image": "doctor1.jpg",
                "rating": 4.8,
                "experience_years": 15,
                "is_available": true
            }
        ]
    }
}

Get Doctor Details¶

GET /public/doctors/{id}

Get detailed information about a specific doctor.

Response:

{
    "success": true,
    "data": {
        "doctor": {
            "id": 1,
            "name": "Dr. John Smith",
            "specialization": "Cardiologist",
            "department": "Cardiology",
            "image": "doctor1.jpg",
            "biography": "Dr. Smith has been practicing cardiology...",
            "qualifications": ["MBBS", "MD Cardiology", "FACC"],
            "experience_years": 15,
            "languages": ["English", "Spanish"],
            "rating": 4.8,
            "total_reviews": 127,
            "consultation_fee": 150.00
        }
    }
}

📅 Appointment Management¶

Get Appointments¶

GET /appointments Requires Authentication

Get user's appointments (patients see their appointments, staff see all).

Query Parameters: - status (optional): Filter by status (scheduled, completed, cancelled) - date_from (optional): Filter from date (Y-m-d) - date_to (optional): Filter to date (Y-m-d) - doctor_id (optional): Filter by doctor - page (optional): Page number for pagination

Response:

{
    "success": true,
    "data": {
        "appointments": [
            {
                "id": 1,
                "patient_name": "John Doe",
                "doctor_name": "Dr. Smith",
                "department": "Cardiology",
                "appointment_date": "2024-08-15",
                "appointment_time": "10:00:00",
                "status": "scheduled",
                "notes": "Regular checkup",
                "created_at": "2024-08-10T09:00:00Z"
            }
        ],
        "pagination": {
            "current_page": 1,
            "total_pages": 3,
            "per_page": 10,
            "total": 25
        }
    }
}

Get Appointment Details¶

GET /appointments/{id} Requires Authentication

Get detailed information about a specific appointment.

Response:

{
    "success": true,
    "data": {
        "appointment": {
            "id": 1,
            "patient": {
                "id": 1,
                "name": "John Doe",
                "phone": "+1234567890"
            },
            "doctor": {
                "id": 1,
                "name": "Dr. Smith",
                "specialization": "Cardiologist"
            },
            "department": "Cardiology",
            "appointment_date": "2024-08-15",
            "appointment_time": "10:00:00",
            "status": "scheduled",
            "notes": "Regular checkup",
            "consultation_fee": 150.00,
            "can_cancel": true
        }
    }
}

Book Appointment¶

POST /appointments Requires Authentication

Book a new appointment.

Request Body:

{
    "doctor_id": 1,
    "appointment_date": "2024-08-15",
    "appointment_time": "10:00:00",
    "notes": "Regular checkup",
    "patient_id": 1 // Optional for staff booking for others
}

Response:

{
    "success": true,
    "message": "Appointment booked successfully",
    "data": {
        "appointment": {
            "id": 1,
            "appointment_date": "2024-08-15",
            "appointment_time": "10:00:00",
            "status": "scheduled",
            "booking_reference": "APT-001"
        }
    }
}

Update Appointment¶

PUT /appointments/{id} Requires Authentication

Update an existing appointment.

Request Body:

{
    "appointment_date": "2024-08-16",
    "appointment_time": "11:00:00",
    "notes": "Updated notes"
}

Cancel Appointment¶

POST /appointments/{id}/cancel Requires Authentication

Cancel an appointment.

Request Body:

{
    "cancellation_reason": "Personal emergency"
}

Response:

{
    "success": true,
    "message": "Appointment cancelled successfully",
    "data": {
        "appointment": {
            "id": 1,
            "status": "cancelled",
            "cancellation_reason": "Personal emergency",
            "cancelled_at": "2024-08-10T15:30:00Z"
        }
    }
}

Get Available Slots¶

GET /appointments/slots/available Requires Authentication

Get available appointment slots for a doctor.

Query Parameters: - doctor_id (required): Doctor ID - date (required): Date to check (Y-m-d)

Response:

{
    "success": true,
    "data": {
        "available_slots": [
            "09:00:00",
            "09:30:00",
            "10:00:00",
            "10:30:00",
            "14:00:00",
            "14:30:00"
        ],
        "doctor": {
            "id": 1,
            "name": "Dr. Smith",
            "consultation_duration": 30
        }
    }
}

👤 Patient Management¶

Get Patient Profile¶

GET /patient/profile Requires Patient Authentication

Get patient's detailed profile information.

Response:

{
    "success": true,
    "data": {
        "patient": {
            "id": 1,
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com",
            "phone": "+1234567890",
            "date_of_birth": "1990-01-01",
            "gender": "male",
            "address": "123 Main St",
            "blood_group": "O+",
            "medical_history": "No significant history",
            "emergency_contact": {
                "name": "Jane Doe",
                "relationship": "spouse",
                "phone": "+1234567891"
            }
        }
    }
}

Update Patient Profile¶

PUT /patient/profile Requires Patient Authentication

Update patient profile information.

Request Body:

{
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890",
    "address": "456 New Address",
    "blood_group": "O+"
}

Upload Profile Photo¶

POST /patient/profile/photo Requires Patient Authentication

Upload patient profile photo.

Request Body: (multipart/form-data) - photo: Image file (JPG, PNG, max 2MB)

Response:

{
    "success": true,
    "message": "Profile photo uploaded successfully",
    "data": {
        "photo_url": "https://domain.com/uploads/patients/photo123.jpg"
    }
}

Get Medical History¶

GET /patient/medical-history Requires Patient Authentication

Get patient's medical history and records.

Response:

{
    "success": true,
    "data": {
        "medical_records": [
            {
                "id": 1,
                "date": "2024-08-01",
                "doctor": "Dr. Smith",
                "department": "Cardiology",
                "diagnosis": "Hypertension",
                "prescription": "Medication details...",
                "notes": "Patient notes..."
            }
        ],
        "prescriptions": [
            {
                "id": 1,
                "date": "2024-08-01",
                "doctor": "Dr. Smith",
                "medications": [
                    {
                        "name": "Lisinopril",
                        "dosage": "10mg",
                        "frequency": "Once daily"
                    }
                ]
            }
        ]
    }
}

🔔 Notification Management¶

Get Notifications¶

GET /notifications Requires Authentication

Get user's notifications.

Query Parameters: - type (optional): Filter by type (appointment, medical, billing) - unread_only (optional): Show only unread notifications - page (optional): Page number

Response:

{
    "success": true,
    "data": {
        "notifications": [
            {
                "id": 1,
                "title": "Appointment Reminder",
                "message": "You have an appointment tomorrow at 10:00 AM",
                "type": "appointment",
                "read_at": null,
                "created_at": "2024-08-10T09:00:00Z",
                "data": {
                    "appointment_id": 1
                }
            }
        ],
        "unread_count": 3
    }
}

Get Unread Count¶

GET /notifications/unread-count Requires Authentication

Get count of unread notifications.

Response:

{
    "success": true,
    "data": {
        "unread_count": 5
    }
}

Mark as Read¶

POST /notifications/{id}/read Requires Authentication

Mark a specific notification as read.

Response:

{
    "success": true,
    "message": "Notification marked as read"
}

Mark All as Read¶

POST /notifications/mark-all-read Requires Authentication

Mark all notifications as read.

Response:

{
    "success": true,
    "message": "All notifications marked as read"
}

Delete Notification¶

DELETE /notifications/{id} Requires Authentication

Delete a specific notification.

Response:

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

👨‍⚕️ Doctor Information¶

Get Doctor Schedule¶

GET /doctors/{id}/schedule Requires Authentication

Get doctor's working schedule.

Query Parameters: - date_from (optional): Start date (Y-m-d) - date_to (optional): End date (Y-m-d)

Response:

{
    "success": true,
    "data": {
        "schedule": [
            {
                "day": "monday",
                "start_time": "09:00:00",
                "end_time": "17:00:00",
                "break_start": "12:00:00",
                "break_end": "13:00:00",
                "is_available": true
            }
        ],
        "exceptions": [
            {
                "date": "2024-08-15",
                "reason": "Medical conference",
                "is_available": false
            }
        ]
    }
}

🏥 Department Statistics¶

Get Department Statistics¶

GET /departments/{id}/statistics Requires Authentication

Get department performance statistics.

Response:

{
    "success": true,
    "data": {
        "statistics": {
            "total_doctors": 8,
            "total_patients": 245,
            "appointments_this_month": 89,
            "completion_rate": 95.5,
            "average_rating": 4.7
        }
    }
}

👨‍💼 Admin Endpoints¶

Get All Patients¶

GET /admin/patients Requires Admin Authentication

Get list of all patients (admin/staff only).

Query Parameters: - search (optional): Search by name or email - status (optional): Filter by status - page (optional): Page number

Response:

{
    "success": true,
    "data": {
        "patients": [
            {
                "id": 1,
                "full_name": "John Doe",
                "email": "john.doe@example.com",
                "phone": "+1234567890",
                "registration_date": "2024-08-01",
                "status": "active",
                "last_appointment": "2024-08-10"
            }
        ]
    }
}

Get All Appointments¶

GET /admin/appointments/all Requires Admin Authentication

Get all appointments across the hospital.

Response:

{
    "success": true,
    "data": {
        "appointments": [
            {
                "id": 1,
                "patient_name": "John Doe",
                "doctor_name": "Dr. Smith",
                "department": "Cardiology",
                "appointment_date": "2024-08-15",
                "status": "scheduled"
            }
        ]
    }
}

Broadcast Notification¶

POST /admin/notifications/broadcast Requires Admin Authentication

Send notification to multiple users.

Request Body:

{
    "title": "System Maintenance",
    "message": "The system will be down for maintenance...",
    "type": "system",
    "recipients": "all", // or "patients", "staff", or specific IDs
    "schedule_at": "2024-08-15T10:00:00Z" // optional
}

📡 Real-time Features¶

WebSocket Connection¶

For real-time notifications and updates:

Connection URL:

wss://your-domain.com/ws

Authentication: Include token in connection headers or query parameters.

Events¶

notification.new: New notification received
appointment.updated: Appointment status changed
system.announcement: System-wide announcements

🚨 Error Codes¶

HTTP Status Codes¶

200 - Success
201 - Created successfully
400 - Bad request / Validation error
401 - Unauthorized / Invalid token
403 - Forbidden / Insufficient permissions
404 - Resource not found
422 - Validation failed
429 - Too many requests (rate limiting)
500 - Internal server error

Custom Error Codes¶

{
    "success": false,
    "error_code": "APPOINTMENT_SLOT_UNAVAILABLE",
    "message": "The selected appointment slot is no longer available",
    "errors": {
        "appointment_time": ["This time slot is already booked"]
    }
}

📊 Rate Limiting¶

Limits¶

Authentication: 5 requests per minute
General API: 60 requests per minute
File Uploads: 10 requests per minute
Search: 30 requests per minute

Headers¶

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1629123456

🔧 Development & Testing¶

API Testing¶

Use tools like Postman or curl to test the API:

# Login example
curl -X POST https://your-domain.com/api/v1/auth/login/patient \
  -H "Content-Type: application/json" \
  -d '{
    "email": "patient@example.com",
    "password": "password123"
  }'

# Authenticated request
curl -X GET https://your-domain.com/api/v1/appointments \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json"

Postman Collection¶

A Postman collection file is available in the project root:

postman/Hospital_Management_API.json

📱 Mobile App Integration¶

Required Headers¶

Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
User-Agent: HospitalApp/1.0 (Platform; Version)

Error Handling¶

Always check the success field in responses:

if (response.success) {
    // Handle success
    console.log(response.data);
} else {
    // Handle error
    console.error(response.message);
    if (response.errors) {
        // Handle validation errors
        Object.keys(response.errors).forEach(field => {
            console.error(`${field}: ${response.errors[field].join(', ')}`);
        });
    }
}

Token Management¶

Store tokens securely (iOS Keychain, Android Keystore)
Refresh tokens before expiration
Handle token expiration gracefully
Implement automatic logout on 401 responses

API Version: 1.0
Last Updated: August 13, 2024
Compatibility: NewWaves Hospital Management System v1.0.0

For additional support or questions about the API, please contact the development team or refer to the user manual.

📱 Mobile API Documentation¶

📋 API Overview¶

Base URL¶

Authentication¶

Content Type¶

Response Format¶

🔐 Authentication Endpoints¶

Patient Registration¶

Patient Login¶

Staff Login¶

Logout¶

Get Profile¶

Update Profile¶

Change Password¶

🏥 Public Information Endpoints¶

Get Departments¶

Get Department Details¶

Get Doctors¶

Get Doctor Details¶

📅 Appointment Management¶

Get Appointments¶

Get Appointment Details¶

Book Appointment¶

Update Appointment¶

Cancel Appointment¶

Get Available Slots¶

👤 Patient Management¶

Get Patient Profile¶

Update Patient Profile¶

Upload Profile Photo¶

Get Medical History¶

🔔 Notification Management¶

Get Notifications¶

Get Unread Count¶

Mark as Read¶

Mark All as Read¶

Delete Notification¶

👨‍⚕️ Doctor Information¶

Get Doctor Schedule¶

🏥 Department Statistics¶

Get Department Statistics¶

👨‍💼 Admin Endpoints¶

Get All Patients¶

Get All Appointments¶

Broadcast Notification¶

📡 Real-time Features¶

WebSocket Connection¶

Events¶

🚨 Error Codes¶

HTTP Status Codes¶

Custom Error Codes¶

📊 Rate Limiting¶

Limits¶

Headers¶

🔧 Development & Testing¶

API Testing¶

Postman Collection¶

📱 Mobile App Integration¶

Required Headers¶

Error Handling¶

Token Management¶