1. User Management APIs
These APIs handle everything related to user accounts, profiles, authentication, and management.
1.1. Register API
- Endpoint:
POST /users/register
- Purpose: Allows a user to sign up by providing their basic details such as name, email, phone number, etc.
- Input:
-
Name, email, phone number, and other details.
-
- Output:
-
-
User ID, authentication token, etc.
-
1.2. Login API
- Endpoint:
POST /users/login
- Purpose: Allows a user to authenticate and log in.
- Input:
-
Email/phone number and password.
-
- Output:
-
-
Auth token, user details.
-
1.3. Update Profile API
- Endpoint:
PUT /users/{userId}/profile
- Purpose: Allows users to update their profile (name, phone number, or payment details).
- Input:
-
Updated user details (e.g., phone number, name).
-
- Output:
-
-
Confirmation of the update.
-
2. Ride Request and Ride Management APIs
These are the core APIs for managing ride requests, ride status updates, and matching users with drivers.
2.1. Request Ride API
- Endpoint:
POST /rides/request
- Purpose: Allows a passenger to request a ride.
- Input:
-
Pickup location, drop-off location, ride type (economy, premium, etc.).
-
- Output:
-
-
Ride ID, estimated time of arrival (ETA), driver info.
-
2.2. Accept Ride API
- Endpoint:
POST /rides/{rideId}/accept
- Purpose: Allows a driver to accept a ride request.
- Input:
-
Driver ID, ride ID.
-
- Output:
-
-
Confirmation that the ride is accepted.
-
2.3. Ride Status Update API
- Endpoint:
PUT /rides/{rideId}/status - Purpose: Allows updating the status of the ride (e.g., in-progress, completed, cancelled).
- Input:
-
New status, timestamp.
-
- Output:
-
-
Updated ride status.
-
2.4. End Ride API
- Endpoint:
POST /rides/{rideId}/end
- Purpose: Marks the ride as completed after the passenger reaches their destination.
- Input:
-
Ride ID, destination confirmation.
-
- Output:
-
-
Confirmation of ride completion.
-
3. GPS & Location APIs
These APIs are responsible for location tracking, route optimization, and real-time geospatial data.
3.1. Get Location API
- Endpoint:
GET /users/{userId}/location
- Purpose: Retrieves the real-time location of a user or driver.
- Input:
-
User or driver ID.
-
- Output:
-
-
Latitude and longitude of the current location.
-
3.2. Track Ride Location API
- Endpoint:
GET /rides/{rideId}/location
- Purpose: Allows the passenger or driver to track the location of the other party in real-time.
- Input:
-
Ride ID.
-
- Output:
-
-
Location data (latitude, longitude).
-
3.3. Route Optimization API
- Endpoint:
POST /rides/{rideId}/route
- Purpose: Provides optimized routing from the pickup point to the drop-off point.
- Input:
-
Pickup and drop-off coordinates, traffic conditions.
-
- Output:
-
-
Optimized route and estimated time.
-
4. Payment APIs
These APIs facilitate transactions between the passengers and the drivers and help manage payments and receipts.
4.1. Add Payment Method API
- Endpoint:
POST /users/{userId}/payment-methods
- Purpose: Allows users to add their payment details (credit/debit card, PayPal, etc.).
- Input:
-
Payment details (card number, expiry, CVV).
-
- Output:
-
-
Confirmation of payment method addition.
-
4.2. Process Payment API
- Endpoint:
POST /rides/{rideId}/payment
- Purpose: Processes the payment for a completed ride.
- Input:
-
Ride ID, payment details (amount, payment method).
-
- Output:
-
-
Payment status (success/failure), receipt.
-
4.3. Transaction History API
- Endpoint:
GET /users/{userId}/transactions
- Purpose: Retrieves the transaction history for a user.
- Input:
-
User ID.
-
- Output:
-
-
List of completed payments, amounts, and dates.
-
5. Driver Management APIs
These APIs handle everything related to drivers, including onboarding, availability, and ratings.
5.1. Driver Onboarding API
- Endpoint:
POST /drivers/onboard
- Purpose: Allows a driver to sign up and provide necessary details (vehicle info, license, etc.).
- Input:
-
Driver details (vehicle type, license, background check).
-
- Output:
-
-
Driver ID, onboarding status.
-
5.2. Update Driver Availability API
- Endpoint:
PUT /drivers/{driverId}/availability
- Purpose: Allows drivers to set their availability (whether they are online or offline).
- Input:
-
Driver ID, availability status.
-
- Output:
-
-
Updated driver availability.
-
5.3. Driver Rating API
- Endpoint:
POST /rides/{rideId}/driver-rating
- Purpose: Allows passengers to rate drivers after a completed ride.
- Input:
-
Ride ID, rating score (e.g., 1-5), feedback (optional).
-
- Output:
-
-
Confirmation of rating submission.
-
6. Notification & Messaging APIs
These APIs handle push notifications, messages, and alerts between the user, driver, and the platform.
6.1. Send Ride Confirmation Notification API
- Endpoint:
POST /notifications/ride-confirmation
- Purpose: Sends a notification to the passenger and driver once a ride is confirmed.
- Input:
-
Ride details (pickup time, location, driver info).
-
- Output:
-
-
Delivery status of the notification.
-
6.2. Send Arrival Notification API
- Endpoint:
POST /notifications/driver-arrival
- Purpose: Sends a notification when the driver has arrived at the pickup location.
- Input:
-
Driver details, ETA.
-
- Output:
-
-
Delivery status of the notification.
-
7. Surge Pricing APIs
These APIs manage dynamic pricing based on demand and supply in real-time.
7.1. Get Surge Pricing API
- Endpoint:
GET /pricing/surge
- Purpose: Retrieves current surge pricing for a given location.
- Input:
-
Location (pickup area).
-
- Output:
-
-
Surge multiplier (if any), surge reason.
-
7.2. Apply Surge Pricing API
- Endpoint:
POST /rides/{rideId}/surge-pricing
- Purpose: Applies surge pricing during high-demand periods.
- Input:
-
Surge pricing multiplier, reason (e.g., high demand, bad weather).
-
- Output:
-
-
Ride fare with surge pricing.
-
8. Ratings & Feedback APIs
These APIs allow users and drivers to provide feedback on their experiences.
8.1. Submit Feedback API
- Endpoint:
POST /rides/{rideId}/feedback
- Purpose: Allows both passengers and drivers to submit feedback after the ride.
- Input:
-
Ride ID, feedback text.
-
- Output:
-
-
Confirmation of feedback submission.
-
