Implementing RESTful API Logic with Mule Flows
APIkit-driven routing
When you scaffold from a spec, the APIkit Router (<apikit:router config-ref="api-config"/>) sits in the main flow right after the HTTP Listener. It matches method plus path and routes to flows named exactly like get:\orders:api-config or post:\orders\{orderId}\items:api-config. The suffix must equal the router's config name; a mismatch produces a runtime NOT_FOUND rather than a compile error. Scaffolding also creates the console flow, and api-console/ is served by default.
Reading the request
Mule 4 exposes HTTP metadata under attributes: method, requestPath, queryParams, uriParams, headers. The body is payload; the listener's or component's outputMimeType (and targetVariable) controls how it is parsed and where it lands.
Composing logic
Use choice for branching, scatter-gather for parallel independent calls (it fails if any route fails), first-successful for failover, and flow-ref to reuse flows without starting a new event context - variables stay visible. Keep orchestration in flows and transformation in DataWeave.
Error mapping
APIkit raises APIKIT:NOT_FOUND, APIKIT:METHOD_NOT_ALLOWED, APIKIT:NOT_ACCEPTABLE, APIKIT:BAD_REQUEST, and APIKIT:UNSUPPORTED_MEDIA_TYPE. Map these in an error handler to return correct HTTP statuses; the default APIkit handler already maps them sensibly.
Traps
- Conflicting listener paths or two listeners on the same host/port block deployment.
scatter-gatherdoes not return partial success; the whole event errors.- URI parameters are strings - coerce before numeric comparisons.
Rule of thumb
A 404 on a URL that looks correct usually means the generated flow name no longer matches the spec path or the router config name.