Platform API Design

A platform API is the contract through which internal customers and automation consume a platform capability. It may be expressed as HTTP, events, declarative resources, configuration schemas, a CLI, or a language library. The design problem is the same: translate user intent into predictable lifecycle behavior without leaking every provider detail or hiding information needed to operate the result.

Start with the capability and its resource model, not URL spelling. Identify actors, resources, ownership, tenancy, actions, invariants, and state transitions. “Database” is not merely a create endpoint: it has plans, credentials, readiness, updates, backup behavior, ownership transfer, and deletion semantics. If the lifecycle is vague, the API will preserve that vagueness in a harder-to-change form.

Intent and resources