06-big-tree-and-apis/07-debuggable-api-design.md

Debuggable API design

APIs should be designed so their behavior is easy to inspect, log, and reason about during debugging.

This is especially important when LLMs and developers need to diagnose problems quickly.

Principles

1. **Explicit method names** – operations should clearly describe what they do. 2. **Stable request shapes** – callers should not need to guess parameter formats. 3. **Stable response shapes** – predictable output simplifies UI integration and debugging. 4. **Actionable errors** – errors should explain what failed and why. 5. **Minimal side effects** – scripts should avoid hidden changes outside their scope.

Logging and inspection

APIs should be easy to trace in logs or debugging tools.

This means:

clear method names
explicit parameters
predictable response structure

These properties make it easier to replay operations and reason about state transitions.

Client integration

API client helpers should expose simple functions with descriptive names.

Example:

export async function getClientInfo() {
  const res = await btRun("db_rpc", {
    method: "debug.getClientInfo",
    params: {}
  });

  return res?.result;
}

The helper hides transport details and exposes a clear operation.

Final rule

Design APIs so a reader can understand what they do, how they fail, and how to debug them without inspecting many unrelated files.