Rides¶
Endpoints for requesting, cancelling, and progressing a ride through its lifecycle. See Ride Flow for the full state machine.
Customer endpoints¶
Request a ride¶
POST /api/rides 🔒 CUSTOMER
Creates a ride and immediately triggers async driver matching. The HTTP response returns before any driver is found.
Request body
json
{
"pickupLocation": { "lat": 43.6511, "lon": -79.3470 },
"dropoffLocation": { "lat": 43.6780, "lon": -79.4090 },
"serviceType": "STANDARD"
}
serviceType values: STANDARD · XL · POOL · PREMIUM
Response 200 OK
json
{
"rideId": 42,
"status": "SEARCHING"
}
After this response, the customer should subscribe to /topic/customer/{customerId}/ride-status to receive the driver assignment notification.
What happens next (async)
- Server searches Redis Geo for drivers within 3–10 km matching
serviceType. - Up to 3 eligible drivers receive a
RideOfferDTOat/topic/driver/{driverId}/requests. - A 30-second non-blocking timer starts. If no driver accepts, status →
CANCELLED.
Cancel a ride¶
DELETE /api/rides/{rideId} 🔒 CUSTOMER
Cancels a ride. Only allowed in SEARCHING or ACCEPTED status.
Path parameter: rideId — the ride ID returned by POST /api/rides
Response 204 No Content
Error responses
| Status | Condition |
|---|---|
404 Not Found |
Ride does not exist |
409 Conflict |
Ride is not in SEARCHING or ACCEPTED status |
409 Conflict |
Authenticated customer is not the ride owner |
Driver endpoints¶
All driver ride-state endpoints accept the same body:
json
{ "rideId": 42 }
And return 202 Accepted with no body on success.
Accept a ride¶
POST /api/driver/accept 🔒 DRIVER
Assigns the driver to the ride, cancels the acceptance timer, and notifies the customer.
Side effects:
- /topic/customer/{customerId}/ride-status → { status: "ASSIGNED", driverId }
- /topic/ride/{rideId}/expired → "Ride already assigned" (notifies other drivers)
Signal arrival¶
POST /api/driver/arrived 🔒 DRIVER
Sets status to ARRIVED. Notifies customer.
Side effects:
- /topic/customer/{customerId}/ride-status → { status: "ARRIVED", driverId }
Start the ride¶
POST /api/driver/start 🔒 DRIVER
Sets status to IN_PROGRESS. From this point, driver location updates are streamed to the customer.
Side effects:
- /topic/customer/{customerId}/ride-status → { status: "IN_PROGRESS", driverId }
Complete the ride¶
POST /api/driver/complete 🔒 DRIVER
Sets status to COMPLETED. Sends rating prompts to both parties.
Side effects:
- /topic/customer/{customerId}/ride-status → { status: "COMPLETED", driverId }
- /topic/driver/{driverId}/ride-status → { status: "COMPLETED", driverId }
- /topic/customer/{customerId}/ride-rating-prompt → RideStatusDTO
- /topic/driver/{driverId}/ride-rating-prompt → RideStatusDTO
Fare estimation¶
POST /api/fares/estimate 🔒 CUSTOMER
Returns a fare estimate valid for 3 minutes. Uses Haversine distance calculation with a fixed 1.2× surge multiplier.
Request body
json
{
"pickup": { "lat": 43.6511, "lon": -79.3470 },
"dropoff": { "lat": 43.6780, "lon": -79.4090 },
"rideType": "STANDARD",
"currency": "CAD",
"passengerCount": 1
}
rideType values: STANDARD · XL · PREMIUM
Response 200 OK
json
{
"currency": "CAD",
"base": 3.50,
"distanceKm": 4.2,
"durationMin": 12.6,
"surgeMultiplier": 1.2,
"estimatedFare": 14.76,
"breakdown": {
"base": 3.50,
"distance": 6.30,
"time": 2.27,
"surge": 2.40
},
"expiresAt": "2026-04-02T14:35:00Z"
}
Pricing table
| Type | Base | Per km | Per min |
|---|---|---|---|
STANDARD / POOL |
$3.50 | $1.50 | $0.18 |
XL |
$6.00 | $1.80 | $0.25 |
PREMIUM |
$10.00 | $2.50 | $0.35 |