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

Prefer stable platform concepts over thin wrappers around a current provider. A request such as desired region, resilience class, and data-retention policy can survive a provider change better than a payload mirroring a vendor SDK. Abstraction should still expose identifiers, status, events, and diagnostics needed for support.

Declarative APIs accept desired state and reconcile toward it. Imperative APIs request an action. Both are valid. Use declarative semantics for long-lived resources where convergence and drift matter; use explicit commands for transitions that are naturally events, such as promote, rotate, or retry. Do not disguise commands as field changes if that makes intent or audit history ambiguous.

HTTP semantics

When using HTTP, respect the standardized meaning of methods and status codes. Safe methods are intended to be read-only. Idempotent methods can be repeated with the same intended effect, although each request may still produce logging or other incidental effects. Correct semantics allow clients, gateways, caches, and retry logic to behave predictably.

Long-running platform operations should normally return an operation resource or equivalent status handle rather than holding one connection until every provider finishes. Model queued, running, succeeded, failed, and cancelled states; surface timestamps, target resources, progress where meaningful, and actionable failures.

Errors and concurrency

Errors are part of the contract. RFC 9457 defines a standard problem-details format for HTTP APIs using application/problem+json. Define stable problem types, distinguish validation from authorization and conflict, and include a correlation or occurrence identity without leaking secrets or internal stack traces.

Concurrent updates need explicit behavior. Use revisions, entity tags, preconditions, or another compare-and-set mechanism where lost updates matter. Decide how duplicate creates, retries, and partial success behave. “The client should not retry” is not a recovery design.

Evolution and governance

Publish a machine-readable contract such as OpenAPI for HTTP APIs or AsyncAPI for message-driven APIs. Validate examples and schemas in CI. Compatibility is broader than syntax: changing a default, tightening validation, removing an enum value, or changing asynchronous timing can break consumers.

Favor additive evolution, tolerant readers where safe, explicit deprecation, usage discovery, migration guidance, and measured retirement. Platform APIs often sit beneath templates, portals, CLIs, and automation, so one contract change can affect many indirect consumers.

Security is not a gateway afterthought. Define caller identity, tenant and resource authorization, provider delegation, secret handling, audit events, quotas, and abuse limits as part of each capability contract.