Implementation
Microservices & API Documentation
Complete catalog of all 11 deployable microservices and exhaustive API documentation for REST, SOAP, gRPC, and SSE endpoints.
Microservice Catalog (11 Services)
frontend
Port 4200 (HTTP)
Angular 21 Single Page Application. Provides interactive Leaflet maps, vehicle booking, SSE ride telemetry, and settlement UI.
Angular 21
Leaflet
TypeScript
rental-service
Port 8080 (HTTP/REST)
Core domain service. Maintains users, vehicle fleet, bookings, and rentals. Registers Zeebe workers for Camunda process tasks and exposes `/resume`.
Spring Boot 3
Zeebe Worker
PostgreSQL
orchestration (Camunda 8)
Ports 8083 (UI) / 26500 (gRPC)
All-in-one Zeebe workflow engine orchestrating executable BPMN processes (`rental_process`, `maintenance_process`, `update_status`).
Camunda 8.9
Zeebe Engine
bank-service
Port 8000 (SOAP/XML)
Jolie payment service. Exposes WSDL SOAP endpoints for pre-authorizing deposit locks (€10), final ride charges, and unlocking funds.
Jolie
SOAP WSDL
bank-account-registration
Port 8082 (HTTP/REST)
Jolie microservice handling initial bank account creation upon user registration.
Jolie
REST
stations-service
Port 8084 (HTTP/REST)
Manages the Bologna station catalog and simulates physical vehicle operations: lock, unlock, and recharging.
Spring Boot 3
REST
maintenance-service
Port 8085 (HTTP/REST)
In-memory FIFO maintenance queue. Simulates vehicle repairs every day at 09:00, restoring battery level to 100%.
Spring Boot 3
Cron Scheduler
fm-gateway
Port 8091 (HTTP/REST)
Fleet Management gateway. Calculates Bologna routes via GraphHopper OpenStreetMap engine and streams telemetry to Tracking and Battery services.
Spring Boot 3
GraphHopper
tracking-service
Port 8092 (gRPC)
High-performance gRPC microservice tracking current vehicle GPS coordinates during active rides.
gRPC
Spring Boot 3
battery-service
Port 8093 (gRPC)
gRPC microservice monitoring vehicle battery voltage and charge degradation.
gRPC
Spring Boot 3
redis
Port 6379 (RESP)
In-memory cache & Pub/Sub event broker for async decoupling between Camunda workers, balance updates, and SSE streaming.
Redis 7
Pub/Sub
Exhaustive API Documentation
Complete specification of all REST, SOAP, gRPC, and internal endpoints organized into dedicated service sub-subsections.
🧠 Rental Service — Core Rental Controller (:8080)
Map queries, QR Code scan, bookings, process resume, ride termination, damage reports
GET
/api/rentals/map
— Stations map & available vehicles
Required Headers
| Name | Type | Description |
|---|---|---|
| Cookie | String | Session Cookie `JSESSIONID` (authenticated users) |
HTTP Response 200 (OK)
{
"stations": [
{
"id": 1,
"name": "Bologna Central Station",
"latitude": 44.5058,
"longitude": 11.3432,
"availableVehicles": [
{ "id": 101, "category": "CAR", "batteryLevel": 95, "status": "AVAILABLE" }
]
}
]
}
GET
/api/rentals/resume
— Resume BPMN process state & canonical route
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| requestedRoute | String | No | User requested URL (e.g., `/map`, `/ride`) |
HTTP Response 200 (OK)
{
"canonicalRoute": "/ride",
"phase": "RIDE_ACTIVE",
"vehicleId": 101,
"rentalId": 45
}
POST
/api/rentals/scan
— Instant rental via QR Code scan
Request Body (JSON)
{ "vehicleId": 101 }
HTTP Responses
// 200 OK:
{ "success": true, "message": "Rental started successfully", "rentalId": 45 }
// 400 Bad Request:
{ "success": false, "message": "Vehicle unavailable or insufficient funds" }
POST
/api/rentals/book
— Reserve vehicle for 30 minutes
Request Body (JSON)
{ "stationId": 1, "category": "CAR" }
HTTP Response 200 (OK)
{ "success": true, "vehicleId": 101, "bookingExpiration": "2026-08-11T09:30:00Z" }
GET
/api/rentals/bookings
— Query active booking details
Query Parameters
| Name | Type | Description |
|---|---|---|
| vehicleId | Long | ID of the reserved vehicle |
HTTP Response 200 (OK)
{ "success": true, "vehicleId": 101, "stationName": "Piazza Maggiore", "remainingSeconds": 1420 }
POST
/api/rentals/undoBooking
— Cancel vehicle reservation
Request Body (JSON)
{ "vehicleId": 101 }
HTTP Response 200 (OK)
{ "success": true, "message": "Reservation cancelled. Deposit unlocked." }
POST
/api/rentals/end
— Terminate active ride
Request Body (JSON)
{ "vehicleId": 101 }
HTTP Response 202 (Accepted)
// 202 Accepted (asynchronous Zeebe settlement initiated)
POST
/api/rentals/report/no-report
— Confirm no damage report
HTTP Response 202 (Accepted)
// 202 Accepted
POST
/api/rentals/report
— Submit vehicle damage report
Request Body (JSON)
{
"vehicleId": 101,
"damageDescription": "Worn front brake pads",
"damagedParts": ["BRAKES"]
}
HTTP Response 202 (Accepted)
// 202 Accepted
🔐 Rental Service — Authentication Controller (:8080)
User authentication, session tracking, registration, and logout
POST
/api/auth/login
— User authentication & session start
Request Body (JSON)
{ "email": "user@acme.com", "password": "password123" }
HTTP Response 200 (OK)
{ "userId": 1, "userName": "Mario Rossi", "authenticated": true, "message": "Login successful" }
GET
/api/auth/session
— Verify current session state
HTTP Response 200 (OK)
{ "active": true, "userId": 1, "userName": "Mario Rossi" }
POST
/api/auth/logout
— Logout & invalidate session
HTTP Response 204 (No Content)
// 204 No Content
POST
/api/auth/register
— User registration & Jolie account creation
Request Body (JSON)
{
"name": "Mario Rossi",
"email": "user@acme.com",
"password": "password123",
"initialBalance": 100.0
}
HTTP Response 201 (Created)
{ "success": true, "userId": 1, "message": "User registered and bank account created" }
💳 Rental Service — Account Controller (:8080)
User bank account balance and deposit pre-authorization status
GET
/api/account/balance
— Query balance & deposit lock status
HTTP Response 200 (OK)
{ "balance": 90.0, "blockedAmount": 10.0, "availableBalance": 80.0 }
📡 Rental Service — Notification Stream SSE (:8080)
Server-Sent Events (SSE) stream for real-time ride position, battery level, and balance updates
GET
/api/notifications
— Real-time Server-Sent Events (SSE) stream
Produces: text/event-stream
event: TELEMETRY_UPDATE
data: { "vehicleId": 101, "latitude": 44.4949, "longitude": 11.3426, "batteryLevel": 92 }
🔄 Rental Service — Internal Inter-service Events (:8080)
Secured callbacks between microservices for maintenance candidate queries and completion events
GET
/internal/maintenance/vehicles
— Internal: Query vehicles due for maintenance (>30 days)
Required Headers
| Name | Type | Description |
|---|---|---|
| X-Internal-Service-Token | String | Internal security token for inter-service calls |
HTTP Response 200 (OK)
{ "vehicleIds": [101, 105, 112] }
POST
/internal/maintenance/events/completed
— Internal: Notify maintenance completion callback
Request Body (JSON)
{ "vehicleId": 101, "notes": "Brakes repaired and battery charged to 100%" }
HTTP Response 204 (No Content)
// 204 No Content
POST
/internal/station/events/vehicle-recharged
— Internal: Vehicle recharged event callback
Request Body (JSON)
{ "stationId": 1, "vehicleId": 101, "newBatteryLevel": 100 }
HTTP Response 204 (No Content)
// 204 No Content
🚏 Stations Service APIs (:8084)
Bologna station catalog and physical vehicle unlock, lock, and recharging simulation
GET
/api/stations
— List configured stations
HTTP Response 200 (OK)
[ { "id": 1, "name": "Bologna Central Station", "totalDocks": 15 } ]
GET
/api/stations/{stationId}
— Query specific station details
HTTP Response 200 (OK)
{ "id": 1, "name": "Bologna Central Station", "totalDocks": 15, "availableVehicles": 10 }
POST
/api/stations/{stationId}/vehicles/{vehicleId}/unlock
— Physically unlock vehicle at dock
Request Body & Response
// Request: { "rentalId": 45 }
// Response: { "stationId": 1, "vehicleId": 101, "status": "UNLOCKED", "success": true }
POST
/api/stations/{stationId}/vehicles/{vehicleId}/lock
— Physically lock vehicle at dock
Request Body & Response
// Request: { "rentalId": 45 }
// Response: { "stationId": 1, "vehicleId": 101, "status": "LOCKED", "success": true }
POST
/api/stations/{stationId}/vehicles/{vehicleId}/recharge
— Initiate simulated vehicle charging
HTTP Response 202 (Accepted)
{ "stationId": 1, "vehicleId": 101, "status": "CHARGING", "success": true }
POST
/api/stations/{stationId}/vehicles/{vehicleId}/no-recharge
— Confirm no recharging needed
HTTP Response 200 (OK)
{ "stationId": 1, "vehicleId": 101, "status": "AVAILABLE", "success": true }
🔧 Maintenance Service APIs (:8085)
FIFO repair queue processing for reported or periodic maintenance vehicles
POST
/api/maintenance/vehicles
— Enqueue vehicle into FIFO repair queue
Required Headers
| Name | Type | Description |
|---|---|---|
| X-Internal-Service-Token | String | Internal security token for inter-service calls |
Request Body (JSON)
{ "vehicleId": 101, "reason": "DAMAGE_REPORT" }
HTTP Response 202 (Accepted)
// 202 Accepted
🚗 Fleet Management Gateway APIs (:8091)
GraphHopper OpenStreetMap route simulation and telemetry gateway
POST
/monitoring/start
— Start vehicle simulation & tracking
Request Body (JSON)
{ "vehicleId": 101, "startStationId": 1, "batteryLevel": 95 }
HTTP Response 200 (OK)
{ "status": "RENTED", "vehicleId": 101 }
GET
/monitoring/telemetry?vehicleId={id}
— Query position & battery telemetry
HTTP Response 200 (OK)
{
"vehicleId": 101,
"batteryLevel": 88,
"latitude": 44.4949,
"longitude": 11.3426,
"isArrived": false,
"destinationStation": 2
}
POST
/monitoring/stop
— Stop vehicle simulation & tracking
Request Body (JSON)
{ "vehicleId": 101 }
HTTP Response 200 (OK)
{ "status": "STOPPED", "vehicleId": 101 }
🏦 Bank Service SOAP Interface (:8000)
Jolie WSDL SOAP service for deposit pre-authorization and settlement
SOAP
blockMoney ( BlockMoneyRequest )
— Pre-authorize €10 deposit lock
SOAP XML Types
// Request: { accountId: "ACC_123" }
// Response: { success: true, token: "TK_ABC987", message: "Money blocked" }
SOAP
unlockMoney ( UnlockMoneyRequest )
— Unlock deposit without charging
SOAP XML Types
// Request: { accountId: "ACC_123", token: "TK_ABC987" }
// Response: { success: true, token: "TK_ABC987", message: "Money unlocked" }
SOAP
chargeMoneyBlock ( ChargeMoneyBlockRequest )
— Charge entire pre-authorized deposit
SOAP XML Types
// Request: { accountId: "ACC_123", token: "TK_ABC987" }
// Response: { success: true, token: "TK_ABC987", message: "Full block charged" }
SOAP
chargeMoney ( ChargeMoneyRequest )
— Charge actual ride amount & unlock remainder
SOAP XML Types
// Request: { accountId: "ACC_123", token: "TK_ABC987", amount: "3.50" }
// Response: { success: true, token: "TK_ABC987", message: "Charged €3.50" }
SOAP
getBalance ( GetBalanceRequest )
— Read available & blocked account balance
SOAP XML Types
// Request: { accountId: "ACC_123" }
// Response: { success: true, balance: "100.00", blockedAmount: "10.00", availableBalance: "90.00" }
📝 Account Registration Jolie REST API (:8082)
Jolie module for creating initial user bank accounts
POST
/createAccount
— Create initial bank account
Request Body (JSON)
{ "accountId": "ACC_123", "balance": 100.0 }
HTTP Response 200 (OK)
{ "success": true, "message": "Account created successfully" }
📡 gRPC Telemetry & Battery Microservices (:8092 / :8093)
High-frequency Protocol Buffers interfaces for Tracking & Battery Services
gRPC
TrackingService.getPosition ( PositionRequest )
— Real-time GPS coordinate tracking
Proto Spec
message PositionRequest { int64 vehicle_id = 1; }
message PositionResponse {
int64 vehicle_id = 1;
double latitude = 2;
double longitude = 3;
bool is_arrived = 4;
int64 destination_station = 5;
}
gRPC
BatteryService.getBatteryLevel ( BatteryRequest )
— Query battery charge level & voltage
Proto Spec
message BatteryRequest { int64 vehicle_id = 1; }
message BatteryResponse {
int64 vehicle_id = 1;
double battery_level = 2;
}