API_DOCUMENTATION.md

TrueFare Backend API Documentation

Authentication Endpoints

Base Path: /api/auth

POST /api/auth/login/user

• Purpose: User login
• Controller: loginUser
• Access Control: Not enforced in this router
• Validation:
  • Body: userLoginSchema

POST /api/auth/login/driver

• Purpose: Driver login
• Controller: loginDriver
• Access Control: Not enforced in this router
• Validation:
  • Body: driverLoginSchema

POST /api/auth/register/user

• Purpose: Create a new user account
• Controller: registerUser
• Access Control: Not enforced in this router
• Validation:
  • Body: userRegistrationSchema

POST /api/auth/register/driver

• Purpose: Create a new driver account
• Controller: registerDriver
• Access Control: Not enforced in this router
• Validation:
  • Body: driverRegistrationSchema

GET /api/auth/user/:userId

• Purpose: Get user profile by ID
• Controller: getUserProfile
• Access Control: Not enforced in this router; recommended to require authentication
• Validation:
  • Params: userIdParamSchema

GET /api/auth/stats

• Purpose: Authentication statistics
• Controller: getAuthStats
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Query: authStatsQuerySchema

PATCH /api/auth/bulk-status

• Purpose: Bulk update status of users/drivers
• Controller: bulkUpdateStatus
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Body: bulkStatusUpdateSchema

POST /api/auth/maintenance

• Purpose: Perform auth maintenance operation
• Controller: performMaintenance
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Body: maintenanceOperationSchema

Driver Endpoints

Base Path: /api/drivers

POST /api/drivers/register

• Purpose: Register a new driver
• Controller: registerDriver
• Access Control: Not enforced in this router
• Validation:
  • Body: driverRegistrationSchema

GET /api/drivers/profile/:driverId

• Purpose: Get driver profile
• Controller: getDriverProfile
• Access Control: Not enforced in this router
• Validation:
  • Params: driverIdParamSchema

PUT /api/drivers/profile/:driverId

• Purpose: Update driver profile
• Controller: updateDriverProfile
• Access Control: Not enforced in this router
• Validation:
  • Params: driverIdParamSchema
  • Body: driverUpdateSchema

GET /api/drivers/:driverId/earnings

• Purpose: Get driver earnings
• Controller: getDriverEarnings
• Access Control: Not enforced in this router
• Validation:
  • Params: driverIdParamSchema
  • Query: driverEarningsQuerySchema

GET /api/drivers/:driverId/bids

• Purpose: Get driver bid history
• Controller: getDriverBids
• Access Control: Not enforced in this router
• Validation:
  • Params: driverIdParamSchema
  • Query: driverBidHistoryQuerySchema

GET /api/drivers/:driverId/rides

• Purpose: Get driver ride history
• Controller: getDriverRideHistory
• Access Control: Not enforced in this router
• Validation:
  • Params: driverIdParamSchema
  • Query: driverRideHistoryQuerySchema

PUT /api/drivers/:driverId/location

• Purpose: Update driver location
• Controller: updateDriverLocation
• Access Control: Not enforced in this router
• Validation:
  • Params: driverIdParamSchema
  • Body: driverLocationUpdateSchema

GET /api/drivers/:driverId/stats

• Purpose: Get driver statistics
• Controller: getDriverStats
• Access Control: Not enforced in this router
• Validation:
  • Params: driverIdParamSchema
  • Query: analyticsQuerySchema

GET /api/drivers/:driverId/vehicles

• Purpose: Get driver vehicles
• Controller: getDriverVehicles
• Access Control: Not enforced in this router
• Validation:
  • Params: driverIdParamSchema

POST /api/drivers/:driverId/vehicles

• Purpose: Assign vehicles to driver
• Controller: assignVehiclesToDriver
• Access Control: Not enforced in this router
• Validation:
  • Params: driverIdParamSchema
  • Body: driverVehicleAssignmentSchema

DELETE /api/drivers/:driverId/vehicles

• Purpose: Remove vehicles from driver
• Controller: removeVehiclesFromDriver
• Access Control: Not enforced in this router
• Validation:
  • Params: driverIdParamSchema
  • Body: driverVehicleAssignmentSchema

PATCH /api/drivers/:driverId/vehicle (Deprecated)

• Purpose: Update driver vehicle info (use vehicle endpoints instead)
• Controller: updateDriverProfile
• Access Control: Not enforced in this router
• Validation:
  • Params: driverIdParamSchema
  • Body: driverUpdateSchema

GET /api/drivers/available

• Purpose: List available drivers
• Controller: getAvailableDrivers
• Access Control: Not enforced in this router
• Validation:
  • Query: driverQuerySchema

GET /api/drivers/nearby

• Purpose: Find nearby drivers
• Controller: getNearbyDrivers
• Access Control: Not enforced in this router
• Validation:
  • Query: nearbyDriversQuerySchema

PATCH /api/drivers/bulk-status

• Purpose: Bulk update driver status
• Controller: bulkUpdateDriverStatus
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Body: bulkUpdateDriverStatusSchema

GET /api/drivers/:driverId/analytics

• Purpose: Driver performance analytics
• Controller: getDriverAnalytics
• Access Control: Not enforced in this router
• Validation:
  • Params: driverIdParamSchema
  • Query: driverAnalyticsQuerySchema

GET /api/drivers/connected

• Purpose: List connected drivers (debug/admin)
• Controller: Inline handler (uses getConnectedDrivers())
• Access Control: Not enforced in this router; intended admin/debug
• Validation: None

Ride Request Endpoints

Base Path: /api/ride-requests

GET /api/ride-requests/available

• Purpose: Get available ride requests for drivers
• Controller: getAvailableRideRequests
• Access Control: Not enforced in this router
• Validation:
  • Query: availableRideRequestsQuerySchema

GET /api/ride-requests/:requestId

• Purpose: Get a specific ride request
• Controller: getRideRequest
• Access Control: Not enforced in this router
• Validation:
  • Params: requestIdParamSchema

GET /api/ride-requests/user/:userId

• Purpose: Get all ride requests for a user
• Controller: getUserRideRequests
• Access Control: Not enforced in this router
• Validation:
  • Params: userIdParamSchema
  • Query: getRideRequestsQuerySchema

GET /api/ride-requests/:requestId/bids

• Purpose: Get bids for a ride request
• Controller: getRideRequestBids
• Access Control: Not enforced in this router
• Validation:
  • Params: requestIdParamSchema
  • Query: getBidsQuerySchema

GET /api/ride-requests/analytics

• Purpose: Ride request analytics
• Controller: getRideRequestAnalytics
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Query: rideRequestAnalyticsQuerySchema

POST /api/ride-requests/bulk-cancel

• Purpose: Bulk cancel ride requests
• Controller: bulkCancelRequests
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Body: bulkCancelRequestsSchema

POST /api/ride-requests/optimize-matching

• Purpose: Optimize ride matching
• Controller: optimizeMatching
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Body: optimizeMatchingSchema

User Endpoints

Base Path: /api/users

POST /api/users/register

• Purpose: Register a new user
• Controller: registerUser
• Access Control: Not enforced in this router
• Validation:
  • Body: userRegistrationSchema

GET /api/users/profile/:userId

• Purpose: Get user profile
• Controller: getUserProfile
• Access Control: Not enforced in this router
• Validation:
  • Params: userIdParamSchema

PUT /api/users/profile/:userId

• Purpose: Update user profile
• Controller: updateUserProfile
• Access Control: Not enforced in this router
• Validation:
  • Params: userIdParamSchema
  • Body: userUpdateSchema

GET /api/users/:userId/ride-history

• Purpose: Get user ride history
• Controller: getUserRideHistory
• Access Control: Not enforced in this router
• Validation:
  • Params: userIdParamSchema
  • Query: userRideHistoryQuerySchema

GET /api/users/:userId/stats

• Purpose: Get user statistics
• Controller: getUserStats
• Access Control: Not enforced in this router
• Validation:
  • Params: userIdParamSchema
  • Query: analyticsQuerySchema

Vehicle Endpoints

Base Path: /api/vehicles

GET /api/vehicles/search

• Purpose: Search vehicles for a ride
• Controller: searchVehiclesForRide
• Access Control: Not enforced in this router
• Validation:
  • Query: vehicleSearchForRideSchema

GET /api/vehicles/by-type

• Purpose: Get vehicles filtered by type
• Controller: getVehiclesByType
• Access Control: Not enforced in this router
• Validation:
  • Query: vehicleByTypeQuerySchema

GET /api/vehicles/statistics

• Purpose: Get vehicle statistics
• Controller: getVehicleStatistics
• Access Control: Not enforced in this router
• Validation:
  • Query: vehicleStatisticsQuerySchema

GET /api/vehicles/analytics

• Purpose: Vehicle analytics
• Controller: getVehicleAnalytics
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Query: vehicleAnalyticsSchema

GET /api/vehicles/maintenance-recommendations

• Purpose: Get vehicle maintenance recommendations
• Controller: getMaintenanceRecommendations
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Query: maintenanceRecommendationsQuerySchema

PATCH /api/vehicles/bulk-status

• Purpose: Bulk update vehicle statuses
• Controller: bulkUpdateVehicleStatus
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Body: bulkVehicleStatusUpdateSchema

POST /api/vehicles/optimize-allocation

• Purpose: Optimize vehicle allocation
• Controller: optimizeVehicleAllocation
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Body: vehicleAllocationOptimizationSchema

GET /api/vehicles

• Purpose: List all vehicles
• Controller: getVehicles
• Access Control: Not enforced in this router
• Validation:
  • Query: vehicleQuerySchema

POST /api/vehicles

• Purpose: Create a new vehicle
• Controller: createVehicle
• Access Control: Not enforced in this router
• Validation:
  • Body: vehicleCreationSchema

GET /api/vehicles/:vehicleId

• Purpose: Get a specific vehicle
• Controller: getVehicle
• Access Control: Not enforced in this router
• Validation:
  • Params: vehicleIdSchema

PUT /api/vehicles/:vehicleId

• Purpose: Update a vehicle
• Controller: updateVehicle
• Access Control: Not enforced in this router
• Validation:
  • Params: vehicleIdSchema
  • Body: vehicleUpdateSchema

PATCH /api/vehicles/:vehicleId/status

• Purpose: Update vehicle status
• Controller: updateVehicleStatus
• Access Control: Not enforced in this router
• Validation:
  • Params: vehicleIdSchema
  • Body: vehicleStatusUpdateSchema

DELETE /api/vehicles/:vehicleId

• Purpose: Delete a vehicle
• Controller: deleteVehicle
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Params: vehicleIdSchema

PUT /api/users/:userId/location

• Purpose: Update user location
• Controller: updateUserLocation
• Access Control: Not enforced in this router
• Validation:
  • Params: userIdParamSchema
  • Body: userLocationUpdateSchema

PUT /api/users/:userId/preferences

• Purpose: Update user preferences
• Controller: updateUserPreferences
• Access Control: Not enforced in this router
• Validation:
  • Params: userIdParamSchema
  • Body: userPreferencesUpdateSchema

GET /api/users/:userId/recommendations

• Purpose: Get personalized vehicle recommendations
• Controller: getPersonalizedRecommendations
• Access Control: Not enforced in this router
• Validation:
  • Params: userIdParamSchema
  • Query: userRecommendationsQuerySchema

GET /api/users/:userId/favorites

• Purpose: Get user's favorite drivers and vehicles
• Controller: getUserFavorites
• Access Control: Not enforced in this router
• Validation:
  • Params: userIdParamSchema

GET /api/users/analytics

• Purpose: User analytics
• Controller: getUserAnalytics
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Query: userAnalyticsQuerySchema

PATCH /api/users/bulk-preferences

• Purpose: Bulk update user preferences
• Controller: bulkUpdatePreferences
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Body: bulkUpdatePreferencesSchema

Admin Endpoints

Base Path: /api/admin

GET /api/admin/stats

• Purpose: Ride request statistics
• Controller: Inline (uses DataPersistenceService.getRideRequestStats)
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Query: adminStatsQuerySchema

GET /api/admin/driver/:driverId/bids

• Purpose: Driver bid history
• Controller: Inline (uses DataPersistenceService.getDriverBidHistory)
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Params: driverIdParamSchema
  • Query: adminPaginationSchema

GET /api/admin/user/:userId/rides

• Purpose: User ride history
• Controller: Inline (uses DataPersistenceService.getUserRideHistory)
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Params: userIdParamSchema
  • Query: adminPaginationSchema

GET /api/admin/pending-bids

• Purpose: Pending bids
• Controller: Inline (uses DataPersistenceService.getPendingBids)
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Query: adminPendingBidsQuerySchema

DELETE /api/admin/cleanup

• Purpose: Cleanup old ride requests
• Controller: Inline (uses DataPersistenceService.cleanupOldRequests)
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

GET /api/admin/backup

• Purpose: Backup ride request data
• Controller: Inline (uses DataPersistenceService.backupRideRequestData)
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

GET /api/admin/health

• Purpose: Persistence health check
• Controller: Inline (uses DataPersistenceService.getRideRequestStats, DataPersistenceService.recoverActiveRideRequests)
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

GET /api/admin/analytics/auth

• Purpose: Authentication analytics
• Controller: getAuthStats
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

GET /api/admin/analytics/drivers

• Purpose: Driver analytics
• Controller: getDriverAnalytics
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

GET /api/admin/analytics/rides

• Purpose: Ride request analytics
• Controller: getRideRequestAnalytics
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

GET /api/admin/analytics/users

• Purpose: User analytics
• Controller: getUserAnalytics
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

GET /api/admin/analytics/vehicles

• Purpose: Vehicle analytics
• Controller: getVehicleAnalytics
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

GET /api/admin/analytics/connections

• Purpose: Socket connection analytics
• Controller: getConnectionAnalytics
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

PATCH /api/admin/bulk/auth-status

• Purpose: Bulk update authentication status
• Controller: bulkUpdateStatus
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

PATCH /api/admin/bulk/driver-status

• Purpose: Bulk update driver status
• Controller: bulkUpdateDriverStatus
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

PATCH /api/admin/bulk/user-preferences

• Purpose: Bulk update user preferences
• Controller: bulkUpdatePreferences
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

POST /api/admin/optimize/matching

• Purpose: Optimize ride matching
• Controller: optimizeMatching
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

POST /api/admin/optimize/vehicles

• Purpose: Optimize vehicle allocation
• Controller: optimizeVehicleAllocation
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

POST /api/admin/optimize/sockets

• Purpose: Optimize socket performance
• Controller: optimizeSocketPerformance
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

POST /api/admin/maintenance/auth

• Purpose: Auth maintenance
• Controller: performMaintenance
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

GET /api/admin/maintenance/vehicles

• Purpose: Vehicle maintenance recommendations
• Controller: getMaintenanceRecommendations
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

POST /api/admin/broadcast

• Purpose: Broadcast announcement
• Controller: broadcastAnnouncement
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

GET /api/admin/insights/user-behavior

• Purpose: User behavior insights
• Controller: getUserBehaviorInsights
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation: None

Socket Endpoints

Base Path: /api/socket

GET /api/socket/analytics

• Purpose: Socket analytics
• Controller: getConnectionAnalytics
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Query: socketAnalyticsQuerySchema

GET /api/socket/connected/drivers

• Purpose: Connected drivers
• Controller: Inline (uses getConnectedDrivers)
• Access Control: Not enforced in this router; intended admin/debug
• Validation: None

GET /api/socket/connected/users

• Purpose: Connected users
• Controller: Inline (uses getConnectedUsers)
• Access Control: Not enforced in this router; intended admin/debug
• Validation: None

GET /api/socket/stats

• Purpose: Connection statistics
• Controller: Inline (uses getConnectionStats)
• Access Control: Not enforced in this router; intended admin/debug
• Validation: None

POST /api/socket/broadcast

• Purpose: Broadcast to clients
• Controller: broadcastAnnouncement
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Body: broadcastMessageSchema

POST /api/socket/rooms

• Purpose: Manage socket rooms
• Controller: manageSocketRooms
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Body: socketRoomSchema

POST /api/socket/optimize

• Purpose: Optimize socket performance
• Controller: optimizeSocketPerformance
• Access Control: Not enforced in this router; intended admin-only (add middleware)
• Validation:
  • Body: socketOptimizationSchema