06-big-tree-and-apis/05-rpc-design.md

RPC design

RPC design

Some BigTree scripts expose RPC-style interfaces where a client can call named methods with parameters.

This pattern is useful for debugging tools, remote inspection, and structured operations that may evolve over time.

RPC structure

A typical RPC call contains:

• method – the operation name
• params – an object describing the arguments

Example:

{
  method: "debug.getClientInfo",
  params: {}
}

Naming RPC methods

RPC methods should be descriptive and grouped by domain.

Examples:

• debug.getClientInfo
• debug.getStore
• debug.dispatch

The prefix helps identify the capability group.

Parameter design

Parameters should always be an object.

Good:

{ limit: 50 }

Avoid positional arguments.

RPC stability

RPC methods should remain stable whenever possible.

Changing method names or parameter shapes should be avoided unless the change is clearly justified.

Final rule

RPC methods should be predictable, well-named, and easy to reason about when inspecting remote behavior.