Business APIs and Console Surfaces
Design typed Module operations and bind Console UI to exact generated clients.
Operator workflows use the same business contracts as every other trusted client. A Module declares a Business API, publishes a generated client, and ships an exact Console Surface in its Module Release. Console supplies the authenticated actor and enforces the connected app’s Surface Grant.
Start with the Business API
Model operations around the business capability, not around a framework-wide record abstraction. For a Support Ticket Module, useful operations are:
| Operation | Business behavior |
|---|---|
listTickets |
Return tickets visible to the current actor and tenant. |
createTicket |
Create one ticket with a caller-supplied idempotency key. |
updateTicket |
Apply a revision-bound update to an existing ticket. |
closeTicket |
Close a ticket through its domain transition. |
The OpenAPI contract defines input, output, error, actor, tenant, deadline, and idempotency behavior. Generate clients from that committed contract and check the generated output in the owning repository.
Bind the Surface
ModuleManifest.console names the Surface and its ESM entry. The Module Release
binds that entry to an immutable console_ui_esm artifact. The application
composition selects the exact Module Release and UI artifact digests.
The Surface Grant narrows access to:
- one Module identity and Module Release digest;
- one UI artifact digest;
- one Business API contract digest;
- an explicit set of operation IDs.
Installing or connecting a Surface never grants every operation in the Module.
Call through Surface Gateway
The generated client uses the same-origin Surface Gateway exposed as
ConsoleClient.surfaceApi. Console Service rechecks the browser session, Console actor,
optional tenant, exact connected System, and full Surface Grant before it calls
the target Module.
The browser does not receive target credentials. It must not call a Service base URL, query the Service Store, or invent an undeclared operation.
Design for direct object states
Render each target with one state and a direct reason:
connected: allow operations included in the Surface Grant;unavailable: keep the current data visible when safe and offer retry;incompatible: identify the contract, release, or artifact mismatch;unmanaged: explain that the object is outside the current binding.
Do not turn these states into an app-wide score or silently fall back to a different target.
Authorization checklist
- Verify actor and tenant on the target Module, not only in the browser.
- Bind updates to the current business revision.
- Require an idempotency key for retried writes.
- Propagate the caller deadline and reject expired work.
- Keep Surface operation IDs narrower than the Module contract.
- Return typed problem responses without secrets or transport diagnostics.
Continue with Module Console UI for artifact packaging and Auth and Capabilities for capability design.