Skip to content

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 OK with a human-readable drone status string, or 404 Not Found if 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 OK with the rebuilt drone state string, or 404 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 their orderIds 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.