06-big-tree-and-apis/01-api-design-principles.md

API design principles

API design principles

Vroq apps should design APIs so they are easy to understand, easy to reuse, and easy to debug.

These principles apply to both BigTree scripts and app-side API clients.

1. Keep boundaries explicit

A clear API boundary helps prevent remote logic from leaking into UI files.

Use these layers:

• script or server endpoint
• app-side API client
• reducer/action integration
• UI section or component

2. Use object-shaped arguments

Prefer explicit object arguments over long positional argument lists.

Good:

runThing({ clientId, appId, userId, limit })

Bad:

runThing(clientId, appId, userId, limit)

Object-shaped args are easier to extend and easier for LLMs to read.

3. Keep returned shapes stable

A caller should be able to rely on the response structure.

Avoid returning unrelated shapes for similar cases.

Good APIs have predictable outputs.

4. Keep names intent-based

Prefer names that describe the business action or debugging capability.

Examples:

• files_list
• db_rpc
• debug.getClientInfo

Avoid vague names that hide purpose.

5. Keep transport details isolated

UI code should not need to know:

• raw fetch details
• token wiring
• endpoint construction
• script URL building

That belongs in the API client layer.

Final rule

Design APIs so each layer has one clear responsibility and remote behavior stays easy to inspect and debug.