Contracts, Ownership, APIs, Messaging, Events, and Workflows

Goal

Show how communication style follows business meaning, timing, ownership, and recovery needs.

The previous section mapped the enterprise boundaries. This section chooses how each boundary should communicate. The durable idea is:

The mechanism should express the business relationship, not force the relationship into the mechanism a team already knows.

The Short Version

APIs, commands, events, workflows, and files are not interchangeable transports.

An API asks for an answer now.
A command asks a known owner to perform work.
An event announces a fact that has already happened.
A workflow coordinates a longer-lived process across steps and owners.
A file exchanges a set of records, often on a schedule or at a partner boundary.

A real enterprise solution commonly uses several of them. The architecture becomes coherent when each mechanism has a clear contract owner, failure model, and reason for existing.

Choose by Meaning, Not Fashion

Use a small decision sequence:

What business meaning must cross?
  -> Is an immediate answer required?
  -> Is one receiver responsible for work?
  -> Are many consumers reacting to a fact?
  -> Does progress span waits, decisions, or compensation?
  -> Does a partner require scheduled bulk exchange?

Style	Meaning	Best Fit	Main Recovery Question
Request-response API	"Answer this request now."	Queries, validation, or decisions required in an interactive path.	What does timeout mean, and may the caller retry?
Command message	"Please perform this work."	Durable handoff to a known capability owner.	How is duplicate work prevented, and where does failed work wait?
Event	"This fact has occurred."	Notification to zero, one, or many interested consumers.	Can consumers catch up or replay without corrupting state?
Workflow	"Coordinate this business process."	Multi-step work with waits, branches, deadlines, or compensation.	Where is progress recorded, and who resolves a stuck instance?
File exchange	"Process this bounded record set."	Legacy, bulk, scheduled, or partner-defined exchange.	How are whole-file and record-level errors corrected?

These are starting points, not rigid laws. A payment provider may offer an API for authorization and later send events for settlement. A supplier may accept purchase orders by file and expose an API for status lookup. The combination should still make the business meaning explicit.

A Contract Is More Than a Schema

A schema describes shape. An integration contract describes how two owners work together.

For each interface, record at least:

Contract Area	Decision
Meaning	What does this request, command, event, workflow step, or file represent?
Authority	Which system is allowed to state this fact or request this action?
Ownership	Who approves semantic changes and supports failures?
Timing	Is the response immediate, eventual, scheduled, or deadline-bound?
Delivery	Can delivery repeat, arrive late, or arrive out of order?
Failure	Which errors are retryable, terminal, compensating, or manual?
Change	Which versions coexist, and how are consumers migrated?
Evidence	Which identifiers, timestamps, outcomes, and audit records are retained?

For example, a schema can show that status is a string. The contract must explain whether SHIPPED means a label was created, the warehouse handed over the parcel, or the carrier performed its first scan. That meaning affects customer notifications, support responses, and financial decisions.

Ownership Has Two Layers

Enterprise integration often has both a domain owner and a platform owner.

The domain owner owns business meaning. The order team defines what OrderAccepted means. The fulfillment team defines what makes an order ready for warehouse release. Finance defines when a posting is valid for reconciliation.

The platform owner provides shared capabilities and guardrails. It may operate an API gateway, messaging fabric, workflow runtime, contract registry, partner onboarding process, or shared telemetry conventions.

This separation avoids two extremes:

Point-to-point chaos, where every team invents its own security, retry, naming, and monitoring rules.
A central integration bottleneck, where one team is expected to interpret business concepts it does not own.

Example: Matching the Commerce Paths

Consider four paths after checkout.

Tax and Fraud Decisions

Checkout may need a timely tax quote and an initial fraud decision. A protected API can fit because the caller needs an answer before proceeding. The contract must still define timeouts, safe retries, fallback behavior, and what is shown to the customer.

Warehouse Release

Once the order is accepted, fulfillment work should survive a temporary warehouse outage. A durable command can hand the work to the warehouse owner. The command needs an idempotency key so redelivery does not create a second release.

Shipment Updates

When the warehouse or carrier reports dispatch, several consumers may react: commerce updates the order timeline, notifications contact the customer, support refreshes its view, and analytics records the milestone. An event fits because it announces a fact without asking every consumer to perform the same action.

Exception Resolution

A damaged item, partial allocation, or failed carrier booking may require a longer-lived process with waits, deadlines, retries, and human approval. A workflow can make progress and exceptions visible. The workflow coordinates owners; it should not absorb the business rules and data ownership of every participating domain.

Combine Patterns Without Hiding Them

One business journey can legitimately use several communication styles:

flowchart LR
    A[Checkout] -->|"API: authorize"| B[Payment or fraud]
    A -->|"Command: release order"| C[Warehouse]
    C -->|"Event: shipment dispatched"| D[Subscribers]
    C -->|"Exception"| E[Resolution workflow]
    E -->|"Partner file or API"| F[Supplier or carrier]

The design is not inconsistent because it uses multiple patterns. It is precise because each path expresses a different relationship.

Common Mistakes

Using synchronous APIs for durable background work, causing caller timeouts and receiver outages to spread upstream.
Publishing a command as if it were an event. SendCustomerEmail requests work from an owner; OrderAccepted announces a fact.
Treating a workflow as the owner of every domain decision. Coordination and business ownership are different responsibilities.
Defining payload fields without delivery, failure, version, and support semantics.
Choosing one enterprise integration product and forcing every path through the same abstraction.

If Someone Asks You

How do APIs, messages, events, and workflows differ in enterprise integration?

A good answer is:

An API requests an immediate response, a command hands work to a responsible owner, an event announces a fact, and a workflow coordinates progress across multiple steps or owners. I choose among them by business meaning, timing, coupling, and recovery needs, then define ownership and failure behavior in the contract.

What You Should Remember

Communication should express the business relationship, not hide it.

Questions to Check Your Understanding

Why might one order journey need both an API and an event?
What is the difference between the domain owner and the integration platform owner?
When does a workflow add value instead of merely adding another layer?

Further Study

AsyncAPI documentation - Learn how event-driven interfaces can be documented and governed.
OpenTelemetry signals - See the provider-neutral distinction between traces, metrics, logs, and propagated context used later in this walkthrough.