Platform API and SDK¶

Developer tool — instantiates Platform Core / Extension Design

The surface builders actually touch — the calls, types, and helper libraries that expose the stable core's capabilities behind a deliberate contract while hiding its internals so the core can change underneath.

Platform API and SDK is the surface builders actually touch — the set of calls, types, and helper libraries through which the stable core's capabilities are consumed. Its defining discipline is that it implements a contract instead of leaking internals: it exposes exactly what the platform promises to keep stable, wrapped in safe defaults and ergonomics that make correct use the easy path, and it hides the core's implementation so the core can change underneath without breaking the builders on top. Where the Blueprint decides what the core owns, the API and SDK are how that ownership becomes something a third party can call at 2 a.m. without reading the source.

Example¶

A smart-home hub platform wants independent device makers to build integrations. The core owns device pairing, the local event bus, and the security handshake. The SDK hands a lamp manufacturer a typed Device interface — onPair(), publish(state), subscribe(command) — with safe defaults baked in: auto-retry, back-pressure, a sandboxed credential store, so the naive implementation is already the safe one. Crucially it exposes none of the hub's internal threading or storage.

When the hub later swaps its event bus for a faster implementation, the lamp maker's extension keeps working, because it only ever depended on the published interface, not the guts behind it. The one time a maker reaches around the SDK into an undocumented socket to shave latency, the next core update breaks them — the living argument for why the surface, not the implementation, is the contract.

How it works¶

Expose only the committed core — surface the capabilities the platform promises to keep stable; keep internals genuinely private, not merely undocumented.
Encode the contract in the shape — put lifecycle hooks, error and timeout semantics, and back-pressure into the types and calls themselves, so the compiler and the SDK enforce correct use.
Ship safe defaults — make the easy path the safe path, and provide escape hatches deliberately rather than by leak.
Keep spec, SDK, and examples in lockstep — any drift between what is documented, what is shipped, and what is demonstrated is a broken contract.

Tuning parameters¶

Surface breadth — how much of the core is exposed. A wide surface empowers builders but freezes more of the core against future change; a narrow surface keeps the core free to evolve but forces workarounds.
Default safety vs. control — how much the SDK decides for the builder (retries, timeouts, batching). Strong defaults protect novices; too much magic frustrates experts and hides real cost.
Contract strictness — how firmly the SDK rejects off-contract use. Strict surfaces prevent hidden dependencies; lenient ones ease adoption but let unintended dependencies accrete.^[1]
Language and runtime coverage — one SDK or many. More bindings widen the ecosystem but multiply the surfaces that must stay synchronized with the spec.

When it helps, and when it misleads¶

Its strength is that it collapses the cost of correct use and lets the core evolve behind a stable façade — which is the entire leverage of a platform. A builder can rely on the contract instead of reverse-engineering the implementation, and the platform can rework its internals without an ecosystem-wide break.

Its failure mode is the leaky pass-through: an SDK that exposes internals so that every observable behavior silently becomes a contract nobody can change,^[1] or one where spec, SDK, and examples drift until "the contract" means three different things. The classic misuse is shipping an SDK that documents the current implementation rather than the promised interface — convenient now, an evolution trap later. The discipline that keeps it honest is to treat the published contract as the real product, keep internals truly hidden, and version the surface deliberately so builders know exactly what they may rely on.

How it implements the components¶

The API and SDK realize the delivery side of the core — the components that make the platform's promises callable:

stable_core_responsibility — makes the core's invariant capabilities and guarantees concrete: a stable, callable surface builders can rely on without touching what lies behind it.
extension_point_contract — encodes each extension point's inputs, outputs, lifecycle, and failure semantics in the types and calls themselves, so the contract is executable rather than prose.

It delivers the contract but does not decide the partition it delivers against — that is Platform Architecture Blueprint — nor demonstrate end-to-end use (Platform Reference Implementation), nor make the capabilities discoverable (Platform Capability Catalog and Portal).

Instantiates: Platform Core / Extension Design — the API and SDK are how the core's responsibility becomes something builders can call.
Consumes: Platform Architecture Blueprint — it exposes exactly what the Blueprint marks as core.
Sibling mechanisms: Platform Architecture Blueprint · Platform Reference Implementation · Platform Capability Catalog and Portal · Platform Conformance Test Suite · Platform Extension Manifest · Platform Plugin and Extension Registry · Platform Sandbox and Capability Permissions · Platform Semantic Versioning and Release Train · Platform Ecosystem Change Council · Platform Extension Health and Dependency Dashboard

References¶

[1] Hyrum's Law — with enough users, every observable behavior of an interface will come to be depended on by somebody, regardless of what the contract promised. It is why an SDK must expose a deliberate contract and truly hide internals: whatever leaks becomes a de facto contract you can no longer change. ↩