Don't Panic: Platform API Design

A platform API is the promise a platform makes when it offers a capability to people and automation. The HTTP path, CLI command, event, or configuration file is only the packaging. The actual promise is about what can exist, who owns it, what state it is in, and what happens when reality develops its usual interest in being inconvenient.

Start with the resource model. A managed database is not a create call wearing a database-shaped hat. It has an identity, an owner, a tenant, desired settings, observed status, credentials, readiness, updates, backups, and deletion. If those parts are vague, the API preserves the vagueness and distributes it to every portal, template, and script that has the poor fortune to consume it.

The useful split is between declarative and imperative interactions. Declarative APIs state what should exist and reconcile toward it. Imperative APIs request an action such as promote, rotate, or retry. Neither is morally superior. The question is whether the caller needs a lasting state or a recorded transition. A Boolean that secretly means "start the process" is where an innocent-looking field begins a small administrative coup.

Long-running work needs an operation resource. Return a durable handle, then show queued, running, succeeded, failed, or cancelled state. A request connection is not a workflow state store, even if it waits very earnestly. The same rule helps when a caller retries after a timeout or needs to understand a partial provider failure.

HTTP adds shared rules rather than decorative status numbers. Safe methods are read-only in their requested semantics. Idempotent methods can be repeated with the same intended effect. Preconditions prevent lost updates. RFC 9457 problem details give failures a stable machine-readable shape. These details let clients correct input, retry work, resolve conflicts, or escalate without interpreting a mystery response.

Then comes compatibility, the part that hides in the shrubbery. Removing a field is not the only breaking change. A changed default, tighter validation, vanished enum value, new authorization requirement, or different timing can upset consumers that never knew an implementation changed. Publish the contract with OpenAPI or AsyncAPI, validate schemas and examples, and give deprecation a migration path instead of a ceremonial warning label.

For the fuller map, use the intro for the resource and lifecycle model, the slides for the design choices, and the cheatsheet for review anchors. The practice reference turns those anchors into a review sequence. The exercise asks you to trace a managed database request through retries, concurrency, errors, and final state. That is where a contract stops being a tidy document and becomes a platform capability.