Platform APIs & Abstraction Layers

Designing the interface between a platform and the teams using it — what to expose, and what to hide.

What it is

A platform API is the interface product teams actually interact with — the design question is what underlying complexity to expose versus abstract away, since exposing too much defeats the purpose and abstracting too much removes needed flexibility.

Key points

Right level of abstraction: a platform API that just thinly wraps the underlying cloud provider's API hasn't actually reduced complexity; one that hides every knob may block legitimate edge-case needs.
Escape hatches: good platform APIs deliberately provide an documented, supported way to step outside the abstraction for the cases the golden path doesn't cover — without one, teams route around the platform entirely.
API stability: because many teams build on top of a platform API, breaking changes have an outsized blast radius — platform APIs generally need stronger backward-compatibility guarantees than a typical internal service.
Platform APIs are a product surface with real users (internal engineers) — the same API design discipline (documentation, versioning, clear error messages) that applies to external APIs applies here too.