API Documentation
This document describes the system's public surface: the REST endpoints exposed through the Caddy gateway, the RabbitMQ messaging topology used internally, and the shared data structures exchanged between services.
All paths below are the public paths as seen by a client hitting the gateway on
http://localhost:8080. Caddy strips the /api/orders and /api/drones prefixes before
forwarding to the underlying service.
Customer Service
Routed via /api/orders*.
POST /api/orders
Create a new delivery order. This starts a SAGA and returns immediately (eventual consistency, NFR-06) — fulfilment continues asynchronously in the background.
Request body (CreateOrderRequest):
| Field | Type | Required | Description |
|---|---|---|---|
customerId |
string | yes | Customer identifier. |
fromAddress |
string | yes | Pickup address. |
toAddress |
string | yes | Delivery address. |
packageWeight |
double | yes | Weight of the package (must be > 0). |
requestedDeliveryTime |
datetime | no | Desired delivery time. Defaults to now + 2 hours. |
maxDeliveryTimeMinutes |
int | yes | Maximum acceptable delivery duration, in minutes. |
Response — 201 Created with an OrderResponse:
{
"orderId": "f1c2...",
"sagaId": "9ab3...",
"customerId": "USER_TEST_1",
"fromAddress": "123 Start St",
"toAddress": "456 End Blvd",
"packageWeight": 2.5,
"requestedDeliveryTime": "2026-05-20T15:00:00",
"maxDeliveryTimeMinutes": 45,
"status": "SAGA_STARTED"
}
Use the returned orderId to track progress via the SAGA status endpoint below.
GET /api/orders/{orderId}/saga-status
Query the current state of the SAGA for a given order (FR-06).
Response — 200 OK with a SagaStatusResponse, or 404 Not Found if the order is unknown:
{
"sagaId": "9ab3...",
"orderId": "f1c2...",
"status": "COMPLETED",
"currentStep": "COMPLETED",
"completedSteps": ["ORDER_VALIDATION", "DELIVERY_SCHEDULING", "DRONE_ASSIGNMENT"],
"failureReason": null,
"startTime": "2026-05-20T14:00:00",
"endTime": "2026-05-20T14:00:07"
}
status is one of STARTED, COMPLETED, FAILED, COMPENSATING, COMPENSATED.
GET /api/orders/health
Liveness check. Returns 200 OK with "Customer Service is running".
Drone Service
Routed via /api/drones*. These endpoints expose the event-sourced drone history.
GET /api/drones
Get the current status of the drone assigned to an order.
- Request body (
DroneRequest):{ "orderId": "<order id>" } - Response:
200 OKwith a human-readable drone status string, or404 Not Foundif no drone is currently dispatched for that order.
GET /api/drones/drone/{droneId}/events
Return the full, ordered event history for a drone (Event Sourcing audit trail).
Response — 200 OK with a list of EventSummary, or 404 Not Found:
[
{ "eventType": "DRONE_CREATED", "timestamp": "2026-05-20T14:00:01", "version": 0 },
{ "eventType": "DRONE_DISPATCHED", "timestamp": "2026-05-20T14:00:01", "version": 1 },
{ "eventType": "DRONE_DELIVERED", "timestamp": "2026-05-20T14:00:06", "version": 2 },
{ "eventType": "DRONE_RETURNED", "timestamp": "2026-05-20T14:00:06", "version": 3 }
]
GET /api/drones/order/{orderId}/events
Same as above, but returns the event history for all drones tied to a given order.
GET /api/drones/drone/{droneId}/rebuild
Reconstruct and return the drone's current state by replaying its event history.
- Response:
200 OKwith the rebuilt drone state string, or404 Not Found.
GET /api/drones/health
Liveness check. Returns 200 OK with "Drone service is running".
Operational Endpoints
| Path | Purpose |
|---|---|
/prometheus |
Prometheus UI (proxied by the gateway). |
/customer/actuator/health |
Customer Service Actuator health. |
/customer/actuator/prometheus |
Customer Service metrics (Prometheus format). |
/drone/actuator/health |
Drone Service Actuator health. |
/drone/actuator/prometheus |
Drone Service metrics (Prometheus format). |
The Delivery Service has no public REST API — it participates purely through messaging.
Messaging Topology (RabbitMQ)
Inter-service communication is asynchronous. The system uses two work queues plus a topic exchange for SAGA events.
Work queues
| Queue | Producer | Consumer | Payload |
|---|---|---|---|
order_queue |
Customer Service | Delivery Service | OrderMessage |
drone_queue |
Delivery Service | Drone Service | OrderMessage |
SAGA event exchange
A topic exchange named saga_events_exchange routes all SAGA events by routing key.
| Queue | Bound routing key(s) | Consumer / purpose |
|---|---|---|
saga_events_queue |
saga.* |
Orchestrator — forward progress events. |
saga_compensation_queue |
saga.compensate_order |
Customer-side order compensation. |
drone_compensation_queue |
saga.compensate.drone |
Drone-side compensation (detach drone). |
Representative routing keys: saga.started, saga.validated, saga.delivery_scheduled,
saga.drone_assigned, saga.completed, saga.cancelled, saga.*_failed,
saga.compensate_*.
Shared Data Structures (common module)
These contracts are shared across all services to guarantee orderId integrity (NFR-07).
OrderMessage
The canonical order payload carried on the work queues.
| Field | Type |
|---|---|
orderId |
string |
customerId |
string |
fromAddress |
string |
toAddress |
string |
packageWeight |
double |
requestedDeliveryTime |
datetime |
maxDeliveryTimeMinutes |
int |
Two
OrderMessages are considered equal when theirorderIds match.
CreateOrderRequest
The REST request body for POST /api/orders — same fields as OrderMessage minus orderId
(which the server generates). requestedDeliveryTime is optional.
SAGA events (SagaEvent hierarchy)
Polymorphic events (serialised with a type discriminator) used to coordinate the SAGA:
OrderSagaStartedEvent, OrderValidatedEvent, OrderValidationFailedEvent,
DeliveryScheduledEvent, DeliverySchedulingFailedEvent, DroneAssignedEvent,
DroneAssignmentFailedEvent, OrderCompletedEvent, OrderCancelledEvent,
CompensateOrderEvent, CompensateDeliveryEvent, CompensateDroneEvent.
Drone events (DroneEvent hierarchy)
Persisted by the Drone Service event store: DroneCreatedEvent, DroneDispatchedEvent,
DroneDeliveredEvent, DroneReturnedEvent. Each carries droneId, orderId, timestamp and a
version.