klinik-gunung-docs
Backend

API Routes Documentation

Comprehensive documentation of all API endpoints, route groups, and middleware in the Klinik Gunung Semeru healthcare management system

API Routes Documentation

This comprehensive guide documents all API routes, middleware, and endpoints in the Klinik Gunung Semeru healthcare management system. The system uses Laravel's routing with role-based access control and Sanctum authentication.

Route Architecture

Base URLs

Development: http://localhost:8000/api/v1/
Production:  https://klinikgunung.com/api/v1/

Route Groups

The API is organized into logical groups based on functionality and user roles:

  1. Public Routes (api.php) - General endpoints
  2. Authentication Routes (auth.php) - Login/logout
  3. Role-Based Routes - Admin, Doctor, Nurse, Cashier, etc.
  4. Shared Routes - Common functionality
  5. Miniapp Routes - Mobile application endpoints

Middleware Stack

  • api - API-specific middleware
  • auth:sanctum - Sanctum authentication
  • Role-based middleware (admin, doctor, nurse, etc.)
  • throttle:api - Rate limiting
  • cors - Cross-origin resource sharing

1. Public API Routes (api.php)

Core API Configuration

Route::prefix('v1')->middleware(['api', 'cors'])->group(function () {
    // Versioned API routes
});

Authentication Endpoints

POST /api/v1/auth/login

Authenticate user and return access token.

Middleware: api, cors

Request Body:

{
  "email": "user@example.com",
  "password": "password"
}

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "uuid": "uuid-string",
      "name": "John Doe",
      "email": "user@example.com",
      "role": "patient"
    },
    "token": "bearer_token_here"
  }
}

Status Codes:

  • 200 - Success
  • 401 - Invalid credentials
  • 422 - Validation error

POST /api/v1/auth/register

Register a new user account.

Middleware: api, cors

POST /api/v1/auth/logout

Logout user and invalidate token.

Middleware: auth:sanctum

GET /api/v1/auth/me

Get authenticated user information.

Middleware: auth:sanctum

2. Role-Based Route Groups

Admin Routes (admin.php)

Authentication Required

All admin routes require authentication and admin role.

Route::middleware(['auth:sanctum', 'role:admin'])->group(function () {
    // Admin-only routes
});

Dashboard & Analytics

  • GET /api/v1/admin/dashboard - Admin dashboard data
  • GET /api/v1/admin/statistics - System statistics
  • GET /api/v1/admin/reports - Generate reports

User Management

  • GET /api/v1/admin/users - List all users
  • POST /api/v1/admin/users - Create new user
  • GET /api/v1/admin/users/{id} - Get user details
  • PUT /api/v1/admin/users/{id} - Update user
  • DELETE /api/v1/admin/users/{id} - Delete user

Staff Management

  • GET /api/v1/admin/staff - List all staff
  • POST /api/v1/admin/staff - Create staff member
  • GET /api/v1/admin/staff/{id} - Get staff details
  • PUT /api/v1/admin/staff/{id} - Update staff
  • DELETE /api/v1/admin/staff/{id} - Remove staff

System Configuration

  • GET /api/v1/admin/settings - Get system settings
  • PUT /api/v1/admin/settings - Update system settings
  • GET /api/v1/admin/backups - List system backups
  • POST /api/v1/admin/backups - Create backup

Doctor Routes (doctor.php)

Authentication Required

Route::middleware(['auth:sanctum', 'role:doctor'])->group(function () {
    // Doctor-only routes
});

Patient Care

  • GET /api/v1/doctor/patients - Doctor's assigned patients
  • GET /api/v1/doctor/patients/{id} - Patient medical history
  • POST /api/v1/doctor/consultations - Create consultation
  • PUT /api/v1/doctor/consultations/{id} - Update consultation

Medical Records

  • GET /api/v1/doctor/records - Medical records
  • POST /api/v1/doctor/records - Create medical record
  • PUT /api/v1/doctor/records/{id} - Update medical record

Prescriptions

  • GET /api/v1/doctor/prescriptions - List prescriptions
  • POST /api/v1/doctor/prescriptions - Create prescription
  • PUT /api/v1/doctor/prescriptions/{id} - Update prescription

Nurse Routes (nurse.php)

Authentication Required

Route::middleware(['auth:sanctum', 'role:nurse'])->group(function () {
    // Nurse-only routes
});

Patient Care

  • GET /api/v1/nurse/patients - Assigned patients
  • GET /api/v1/nurse/patients/{id}/vitals - Patient vital signs
  • POST /api/v1/nurse/vitals - Record vital signs
  • PUT /api/v1/nurse/vitals/{id} - Update vital signs

Physical Examinations

  • GET /api/v1/nurse/examinations - Examination schedule
  • POST /api/v1/nurse/examinations - Create examination
  • PUT /api/v1/nurse/examinations/{id} - Update examination
  • GET /api/v1/nurse/examinations/{id} - Examination details

Medication Administration

  • GET /api/v1/nurse/medications - Medication schedule
  • POST /api/v1/nurse/medications/administer - Administer medication
  • GET /api/v1/nurse/medications/history - Medication history

Cashier Routes (cashier.php)

Authentication Required

Route::middleware(['auth:sanctum', 'role:cashier'])->group(function () {
    // Cashier-only routes
});

Payment Processing

  • GET /api/v1/cashier/payments - List payments
  • POST /api/v1/cashier/payments - Create payment
  • GET /api/v1/cashier/payments/{id} - Payment details
  • PUT /api/v1/cashier/payments/{id} - Update payment
  • POST /api/v1/cashier/payments/{id}/process - Process payment

Billing

  • GET /api/v1/cashier/bills - List bills
  • POST /api/v1/cashier/bills - Create bill
  • GET /api/v1/cashier/bills/{id} - Bill details
  • PUT /api/v1/cashier/bills/{id} - Update bill

Financial Reports

  • GET /api/v1/cashier/reports/daily - Daily financial report
  • GET /api/v1/cashier/reports/monthly - Monthly financial report
  • GET /api/v1/cashier/reports/revenue - Revenue analysis

Front Office Routes (front.php)

Authentication Required

Route::middleware(['auth:sanctum', 'role:front_office'])->group(function () {
    // Front office routes
});

Patient Registration

  • GET /api/v1/front/patients - List patients
  • POST /api/v1/front/patients - Register new patient
  • GET /api/v1/front/patients/{id} - Patient details
  • PUT /api/v1/front/patients/{id} - Update patient info

Appointments

  • GET /api/v1/front/appointments - List appointments
  • POST /api/v1/front/appointments - Create appointment
  • PUT /api/v1/front/appointments/{id} - Update appointment
  • DELETE /api/v1/front/appointments/{id} - Cancel appointment

Queue Management

  • GET /api/v1/front/queue - Current queue
  • POST /api/v1/front/queue/call - Call next patient
  • PUT /api/v1/front/queue/{id}/status - Update queue status

3. Screening System Routes (screening.php)

Authentication Required

Route::middleware(['auth:sanctum'])->group(function () {
    // Screening routes
});

Health Screening Management

  • GET /api/v1/screenings - List all screenings
  • POST /api/v1/screenings - Create new screening
  • GET /api/v1/screenings/{id} - Get screening details
  • PUT /api/v1/screenings/{id} - Update screening
  • DELETE /api/v1/screenings/{id} - Delete screening

Questionnaire System

  • GET /api/v1/screenings/questionnaires - List questionnaires
  • GET /api/v1/screenings/questionnaires/{id} - Get questionnaire
  • POST /api/v1/screenings/{id}/answers - Submit answers
  • GET /api/v1/screenings/{id}/answers - Get answers

Screening Results

  • GET /api/v1/screenings/{id}/results - Get screening results
  • POST /api/v1/screenings/{id}/complete - Mark screening complete
  • GET /api/v1/screenings/{id}/certificate - Generate certificate

4. Management Routes (management.php)

Authentication Required

Route::middleware(['auth:sanctum', 'role:admin|manager'])->group(function () {
    // Management routes
});

User Management

  • GET /api/v1/management/users - List all users
  • POST /api/v1/management/users - Create user
  • GET /api/v1/management/users/{id} - Get user details
  • PUT /api/v1/management/users/{id} - Update user
  • DELETE /api/v1/management/users/{id} - Delete user

Staff Management

  • GET /api/v1/management/staff - List all staff
  • POST /api/v1/management/staff - Create staff
  • GET /api/v1/management/staff/{id} - Get staff details
  • PUT /api/v1/management/staff/{id} - Update staff
  • DELETE /api/v1/management/staff/{id} - Remove staff

Clinic Management

  • GET /api/v1/management/clinic/info - Clinic information
  • PUT /api/v1/management/clinic/info - Update clinic info
  • GET /api/v1/management/clinic/settings - Clinic settings
  • PUT /api/v1/management/clinic/settings - Update settings

Reports & Analytics

  • GET /api/v1/management/reports/patients - Patient reports
  • GET /api/v1/management/reports/financial - Financial reports
  • GET /api/v1/management/reports/staff - Staff performance reports
  • GET /api/v1/management/analytics/dashboard - Analytics dashboard

5. Miniapp Routes (miniapp.php)

Authentication Required

Route::middleware(['auth:sanctum', 'miniapp.access'])->group(function () {
    // Miniapp routes
});

Mobile App Features

  • GET /api/v1/miniapp/dashboard - Miniapp dashboard
  • GET /api/v1/miniapp/profile - User profile
  • PUT /api/v1/miniapp/profile - Update profile
  • GET /api/v1/miniapp/appointments - My appointments
  • POST /api/v1/miniapp/appointments - Book appointment

Health Monitoring

  • GET /api/v1/miniapp/health/records - Health records
  • POST /api/v1/miniapp/health/vitals - Record vitals
  • GET /api/v1/miniapp/health/screenings - Screening history

Notifications

  • GET /api/v1/miniapp/notifications - Get notifications
  • PUT /api/v1/miniapp/notifications/{id}/read - Mark as read
  • POST /api/v1/miniapp/notifications/token - Register device token

6. Shared Routes (shared.php)

Authentication Required

Route::middleware(['auth:sanctum'])->group(function () {
    // Shared routes accessible by multiple roles
});

Common Resources

  • GET /api/v1/shared/patients - Patient list (filtered by role)
  • GET /api/v1/shared/patients/{id} - Patient details
  • GET /api/v1/shared/appointments - Appointments
  • GET /api/v1/shared/queue - Current queue status

Utility Endpoints

  • GET /api/v1/shared/search/patients - Search patients
  • GET /api/v1/shared/search/staff - Search staff
  • GET /api/v1/shared/lookup/{type} - Data lookup endpoints

7. Web Routes (web.php)

Public Web Routes

  • GET / - Homepage
  • GET /login - Login page
  • GET /register - Registration page
  • GET /about - About page
  • GET /contact - Contact page

Protected Web Routes

  • GET /dashboard - User dashboard
  • GET /profile - User profile
  • GET /appointments - Appointments page
  • GET /medical-records - Medical records page

8. Additional Route Files

Console Routes (console.php)

Command-line interface routes for scheduled tasks and maintenance.

Channels Routes (channels.php)

Broadcasting channels for real-time features.

AI Routes (ai.php)

Artificial intelligence and machine learning endpoints.

Manager Routes (manager.php)

Management-level operations and analytics.

Middleware Configuration

Custom Middleware Classes

Role-Based Access Control

// app/Http/Middleware/CheckRole.php
class CheckRole
{
    public function handle($request, Closure $next, $role)
    {
        if (!auth()->check() || !auth()->user()->hasRole($role)) {
            return response()->json(['error' => 'Unauthorized'], 403);
        }
        return $next($request);
    }
}

Miniapp Access Control

// app/Http/Middleware/MiniappAccess.php
class MiniappAccess
{
    public function handle($request, Closure $next)
    {
        $accessCode = $request->header('X-Access-Code');
        if (!$this->isValidAccessCode($accessCode)) {
            return response()->json(['error' => 'Invalid access code'], 403);
        }
        return $next($request);
    }
}

Rate Limiting

// Route-specific throttling
Route::middleware(['throttle:strict'])->group(function () {
    // Sensitive operations
});

Route::middleware(['throttle:api'])->group(function () {
    // Standard API calls
});

Error Handling & Responses

Standard Response Format

{
  "success": true|false,
  "message": "Response message",
  "data": {...} | null,
  "errors": {...} | null,
  "meta": {...} | null
}

HTTP Status Codes

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 422 - Validation Error
  • 429 - Too Many Requests
  • 500 - Internal Server Error

Validation Errors

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password must be at least 8 characters."]
  }
}

API Versioning Strategy

The API uses URL-based versioning (/api/v1/) to ensure backward compatibility. Future versions will be added as needed:

  • /api/v1/ - Current stable version
  • /api/v2/ - Future version (when breaking changes are required)

Security Considerations

Authentication

  • JWT tokens via Laravel Sanctum
  • Token expiration and refresh mechanisms
  • Secure password hashing

Authorization

  • Role-based access control (RBAC)
  • Permission-based access
  • Route-level middleware protection

Data Protection

  • Input validation and sanitization
  • SQL injection prevention
  • XSS protection
  • CSRF protection

Rate Limiting

  • API throttling to prevent abuse
  • Different limits for different user roles
  • Monitoring and alerting for suspicious activity

Testing API Endpoints

Using cURL

# Authentication
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password"}'

# Protected endpoint
curl -X GET http://localhost:8000/api/v1/patients \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Using Postman/Insomnia

  1. Create environment variables for base URL and tokens
  2. Set up authentication flows
  3. Create request collections for each route group
  4. Use data variables for dynamic testing

Automated Testing

// Feature test example
public function test_user_can_create_patient()
{
    $user = User::factory()->create(['role' => 'admin']);

    $response = $this->actingAs($user, 'sanctum')
        ->postJson('/api/v1/patients', [
            'nik' => '1234567890123456',
            'name' => 'John Doe',
            'email' => 'john@example.com'
        ]);

    $response->assertStatus(201)
        ->assertJsonStructure(['success', 'data']);
}

This comprehensive API documentation covers all route groups, middleware, authentication mechanisms, and security considerations for the Klinik Gunung Semeru healthcare management system. The modular approach ensures scalability and maintainability as the system grows.

Controllers

Documentation of all controllers in the Klinik Gunung Health Screening System backend

Frontend Introduction

Comprehensive guide to the Klinik Gunung frontend application built with Next.js, TypeScript, and modern React ecosystem