Async Command dispatch

async-command-dispatch.md

Asynchronous Command Dispatch

Scenario

Imagine a Checkout Service (producer) asking an Order Fulfilment Service (consumer) to ship an order.
It does not need to wait for the Order to be shipped; only assurance the fulfilment service will process the request.

Here producer means “producer of the async request”
And consumer as "consumer of the async request".

---

Pitfall: Producer writes straight into the consumer’s queue

Problem	Issue	Impact
Weak assurance	Producer sees only message queued, not message valid	Poison messages pile up.
Tight coupling	Producer must know queue names, wire format, message headers & metadata	Inhibits Consumer iterations.
Upgrade pain	Queues have no built‑in versioning.	Schema change forces lock‑step releases.

---

Better: API façade in front of the queue

1. POST /commands — Producer sends the command to the consumer’s API.
2. Validate → enqueue — Consumer checks the payload, then pushes it onto its private queue.
3. Respond 202 Accepted — Consumer confirms “valid and queued” immediately.

Why this works

• Strong assurance
  • 202 = syntactically & semantically valid and safely queued.
  • 4xx = rejected now; producer can fix and retry.
• Clean contract
  • Producer cares only about the API schema—no accidental coupling to implementation semantics.
• Smooth evolution
  • Version endpoints (/v2/commands) or schemas without breaking existing clients.

Bottom line: use an API for cross‑service hand‑off; hide queues inside the consumer.