You are here. See how this question connects to other ideas.
Select a node to open its page · Expand to read within the map
One question
How do you expose a discoverable action?
An action needs discoverable arguments, effects and failures as well as a handler.
What does “mark ready” promise?
Suppose a report exposes a mark-ready action. A caller needs its address, arguments, state transition and authority requirements. The handler is only part of the interface; listing and explaining the action matter too.
Providers can express this through action descriptors and execution routes. Reading documentation, discovering actions and executing one are separate steps. /work/.actions/mark-ready is an illustrative address; the actual address comes from the provider and its mount.
Define effects before connecting a UI
| Question | Example contract |
|---|---|
| Input | Report identifier and expected version |
| Change | Report moves from draft to ready |
| Authority | Caller may modify that task |
| Repeated call | Explicit idempotency or conflict behavior |
| Failure | Distinguish denial, conflict and missing resource |
These are proposed application semantics, not behavior implemented by every provider. An effect description is not authorization. The execution boundary must enforce the rule.
A discovery-to-execution trace
This is an illustrative application contract; an implementation must supply these paths and responses:
Discover actions on /work
→ mark-ready at /work/.actions/mark-ready
Read its description
→ inputs: reportId, expectedVersion; effect: update report status
Read /work/report before executing
→ status=draft, version=7
exec /work/.actions/mark-ready {reportId:"report", expectedVersion:7}
→ status=ready, version=8
Read /work/report again
→ status=ready, version=8Reading the description does not invoke the business action. expectedVersion means “update only if the report is still the version I read.” A concurrent change should produce the agreed conflict response. Idempotency means repeating the same request does not repeat its business effect; support and request identification require an explicit application contract.
Check your understanding
How do you expose a discoverable action?
An action needs discoverable arguments, effects and failures as well as a handler.
Continue along a learning path
- Build and check a providerStep 3 of 6