DRAFT GUIDANCE - NO PUBLIC ADAPTER YET
Application API Patterns
Desktop and mobile app adapters benefit from operation consolidation when feature surfaces are broad and evolve rapidly.
This is conceptual guidance. A public application adapter reference is not published yet.
On this page
Jump to a section
Use the outline to move through longer pages without losing your place.
Related reading
Read the formal docs
These docs fill in the public contract details that sit behind this pattern page.
Explore more patterns
Compare how the same core rules behave in server, OS, cloud, and web-facing adapter shapes.
When this pattern fits
Best fit
- The source system is a product or application surface with many user-facing actions.
- You need stable operation names over a feature area that evolves quickly.
- Validation, discoverability, and side-effect labeling matter more than mirroring transport details directly.
Watch for
- Action names that reflect UI wording instead of durable operation semantics.
- Large opaque payloads that hide parameter meaning from introspection and clients.
- Retry and idempotency assumptions that are real in practice but unstated in the contract.
Design Guidance
Modeling
- Expose user-facing actions as named operations.
- Prefer explicit parameter schemas over opaque payload blobs.
- Use introspection for dynamic capability discovery.
Runtime Behavior
- Document operation side effects clearly.
- Normalize validation and error handling across endpoints.
- Add idempotency semantics where retries are expected.
Conceptual Example
{
"operation": "create_ticket",
"params": {
"title": "Spec website gap",
"priority": "high"
}
}
Implementation Reference
Development Guide
Turn feature-level actions into stable operations with the reference implementation workflow.
Testing Guide
Validate routing, parameter handling, and introspection so application actions remain predictable.
Schema-Driven Dispatch
Use the dispatch doc when an application surface is too broad for ad hoc routing logic.