04-code-organization/07-api-clients.md

API clients

API clients isolate transport and server interaction from UI and reducers.

Keeping API calls in dedicated client files prevents UI files from mixing presentation with networking logic.

Where API clients live

Feature-specific API clients should live in the feature folder.

Example:

features/files/
  fileApi.js

Shared API helpers used by multiple features may live in:

shared/api/

Responsibilities

An API client should:

call server endpoints or BigTree scripts
normalize responses when necessary
expose simple functions used by sections or actions
isolate transport details

Example

import { btRun } from "../debugger/btClient.js";

export async function listFiles() {
  const result = await btRun("files_list", {});
  return result?.items || [];
}

Rules

keep API clients small
expose clear function names
avoid UI logic inside API files
avoid calling fetch directly from UI sections

Final rule

All remote calls should pass through a small API client so networking behavior is easy to locate and debug.