Skip to content
Fundament Docs

ADR-0010: API architecture

Proposed
Status

proposed

Date

2026-03-09

Group

platform

Depends-on

ADR-0002

Context

At 50,000 physical servers (ADR-0002), every action — tenant onboarding, cluster provisioning, network configuration, storage allocation — must be automatable. This requires a decision on whether the platform is API-first or UI-first, and how the UI relates to the API.

Options

Option 1: API-first

  • Pros: all operations are automatable from day one; UI is just an API client; third-party integrations use the same interface; enables GitOps and IaC workflows; single source of truth for platform state

  • Cons: higher upfront investment in API design; UI development depends on API readiness; slower initial demo-ability

Option 2: UI-first with API added later

  • Pros: faster initial user-facing progress; easier to demo and get stakeholder buy-in; lower initial engineering investment

  • Cons: API becomes an afterthought; UI often accumulates business logic that must be extracted later; dual code paths; automation consumers are second-class citizens

Option 3: Mixed (some operations API, some UI-only)

  • Pros: pragmatic for early stages; critical operations get API first, others can be UI-only initially

  • Cons: inconsistent automation story; some operations cannot be scripted; technical debt accumulates; unclear contract for integrators

Decision

API-first. Every platform operation must be available through a versioned API. The UI consumes the same API as external clients. No operation may exist only in the UI. The UI-first approach was proposed but rejected: at our scale, automation is not optional and retrofitting an API onto UI-first code is more expensive than designing API-first from the start. The mixed approach creates an unpredictable integration surface that external consumers cannot rely on.

Consequences

  • API design is a first-class concern, not an afterthought

  • UI development is decoupled from backend — it is an API client

  • All platform state changes go through the API

  • RPC framework choice must be made (separate ADR)

  • API versioning and compatibility strategy must be defined