Skip to content

Host-Service API Delegation

Delegating interface — instantiates Layer-Appropriate Capability Placement

Forwards a subsystem's capability request to the authoritative host service across a bounded, versioned API, so the host stays the single source of truth instead of being cloned locally.

Host-Service API Delegation is the plumbing by which an embedded subsystem, instead of implementing a capability itself, forwards the request across a defined boundary to the host service that authoritatively owns it — and returns the host's answer. Where a subsystem is tempted to keep its own copy of identity, storage, scheduling, or policy, delegation makes the host the single place that capability lives: the subsystem asks, the host decides and holds the state, and the subsystem consumes the result through a bounded, versioned interface. Its defining move is drawing an explicit delegated-authority boundary — a line that says this side merely requests; that side remains the source of truth — and recording every crossing, so the relationship stays legible rather than a tangle of hidden calls.

Example

A banking app needs to store a login token and a few secrets on the phone. The tempting local build is a small encrypted file with a hand-rolled key — a private credential store the app fully controls. Delegation takes the other path: the app calls the operating system's keychain/keystore API and lets the OS hold the secret, gate access behind the device's biometric prompt, and enforce hardware-backed protection the app could never reproduce. The app never sees the raw key material; it hands the OS a request ("store this; release it only after a face-match") and gets back a handle.

The authority boundary is explicit — the OS owns the secret and the security policy, the app owns only the request — and each store and retrieve is logged so a security reviewer can see exactly what was delegated. When the OS ships a new keychain API version, the app migrates against a documented contract rather than discovering a silent break. The alternative, a bespoke local vault, would have been a smaller, weaker clone of a capability the host already owns — the exact shadow-platform trap the archetype warns against.[1]

How it works

  • Locate the authoritative owner. Identify the host service that already owns the capability and its state, rather than standing up a local equivalent.
  • Forward across a bounded contract. The subsystem issues its request through a defined, versioned API surface — inputs, outputs, and errors specified — and treats the host's response as canonical.
  • Hold the authority line. State and policy stay on the host side of the boundary; the subsystem keeps no shadow copy it would later have to reconcile.
  • Record the crossing. Each delegated call is logged — what was asked, of which host version, with what outcome — so the dependency is observable and auditable.

Tuning parameters

  • Boundary granularity — one coarse "do the whole thing" call versus many fine-grained ones. Coarse hides host detail and eases portability; fine-grained gives control but couples the subsystem tightly to the host's shape.
  • Synchronicity — a blocking call versus a queued/async request. Async survives a slow host but complicates the subsystem; blocking is simple but inherits the host's latency.
  • Result caching — whether responses may be cached locally, and for how long. Caching cuts load and latency but reintroduces a second copy that can go stale — the very duplication delegation exists to avoid.
  • Failure posture — what the subsystem does when the host doesn't answer: fail closed, fail open, or fall back. Sets how far the delegation's reliability is bounded by the host's.
  • Version pinning — whether the subsystem pins to a host API version or floats to latest. Pinning is stable but ages; floating stays current but can break on the host's schedule.

When it helps, and when it misleads

Its strength is that it keeps one source of truth: the capability lives where it is owned, the subsystem stays thin, and a whole class of reconciliation bugs and weaker-clone security holes never gets built. It is the constructive answer to "don't reimplement the host" — the mechanism you reach for the moment a subsystem is tempted to grow its own identity or storage layer.

Its failure modes come from the coupling it creates. A delegated capability is only as available as the host service, so an un-budgeted web of delegations can turn one host outage into a subsystem-wide stall; and a chatty, fine-grained contract can bind the subsystem so tightly to the host's internals that neither can change independently. The misuse to watch is delegation-in-name-only — forwarding to the host but then caching and mutating a local copy "for performance," quietly recreating the second source of truth. The discipline is to keep the authority boundary real (the host's answer is canonical; any local copy is at most a cache with an honest expiry) and to budget and observe the dependency rather than letting delegations accrete invisibly.

How it implements the components

Delegation fills the interface-and-authority side of the archetype — the components that let a subsystem use host capability rather than own it:

  • delegated_authority_boundary — the interface is the boundary: it fixes what the subsystem may request and reserves ownership of state and policy to the host.
  • delegation_observability_record — every forwarded call is logged with its host version and outcome, making the dependency visible to operators and auditors.

It carries the ordinary, standing request path; it does not grant the rare out-of-band privilege that sits outside this surface (that's Privileged Host Escape Hatch), define the interface's version-compatibility contract (that's the sibling API Versioning), or publish the host's catalogue of capabilities (that's Capability Catalog).

Notes

Delegation and the Privileged Host Escape Hatch both let a subsystem use host power and are easily conflated. The difference is standing and breadth: delegation is the ordinary, durable, well-lit interface for capabilities the host means to expose; the escape hatch is a narrow, time-boxed exception for one it doesn't. If a subsystem is routinely reaching through an "escape hatch," that is a signal the capability should be promoted into a real delegated API.

References

[1] "Don't roll your own crypto" — the security maxim that credential and cryptographic facilities should be delegated to well-reviewed platform implementations rather than reimplemented locally, because a hand-built version is almost always weaker. It generalizes to the archetype's core counsel: use the host's capability instead of building an inferior local clone. ↩