Files

3.1 KiB

Web API Wrapper Pattern

Wrap a web API for use through Bot. Focuses on bot-specific integration — execution methods, caching, polling, notifications — not generic REST/HTTP advice.

Bot Execution Methods

Choose based on complexity:

Method When
web_fetch Simple GET, public endpoints, no auth headers
exec + curl Custom headers, POST/PUT/DELETE, auth
Script Repeated calls, response parsing, caching

web_fetch (Simplest)

Use for simple GET requests to public endpoints. See botdocs for current web_fetch tool parameters.

exec + curl (Flexible)

For custom headers, POST/PUT/DELETE, or authentication. Use the exec tool with curl. Consult botdocs /tools/bash for exec tool syntax.

Script (Complex/Repeated)

When API calls are complex or need caching, create <skill>/scripts/client.py.

Bot-Specific Concerns

1. Polling via Cron

For APIs that need periodic checking, use Bot's cron system. Consult botdocs /automation/cron-jobs for configuration format and options.

Skill documents:

  • What endpoint to poll
  • What constitutes "new" (compare to stored state)
  • Notification format and channel

2. State & Caching

Store in <skill>/state.json:

{
  "lastFetch": "2025-01-20T10:00:00Z",
  "lastItemId": "item_123",
  "cache": {"endpoint": {"data": "...", "expires": "..."}}
}

Use cases:

  • Incremental polling (track last-seen ID/timestamp)
  • Avoid redundant calls (cache responses)
  • Rate limit tracking (remember reset time)

3. Heavy Processing (sessions_spawn)

For large responses or analysis:

sessions_spawn task:"Fetch all items from example API, analyze trends, summarize. API key is in EXAMPLE_API_KEY env var."

Path considerations: If sub-agent needs workspace files, consult botdocs /tools/subagents for current sandbox configuration and include path context in the task.

4. Notifications (message)

Push results to channels using the message tool. Consult botdocs /concepts/messages for current parameters and channel options.

5. Channel-Aware Formatting

Use botdocs to check /providers/ docs for channel-specific capabilities. Common considerations:

  • Some channels don't support tables — use bullet lists
  • Long responses should be summarized, offer full on request
  • Rich formatting availability varies by channel

6. Secrets Handling

Document in SKILL.md setup section:

## Setup

Set API key:
\`\`\`bash
export EXAMPLE_API_KEY="your-key"
\`\`\`

Never hardcode keys in scripts. Read from environment.

For OAuth flows, document the process and where tokens are stored (<skill>/auth/ or similar).

Checklist

Bot-specific concerns for API wrappers:

  • Execution method chosen (web_fetch vs curl vs script)
  • Cron polling documented (if periodic)
  • State/cache location uses <skill>/ or <workspace>/
  • Heavy operations spawn sub-agents
  • Notification format and channel documented
  • Secrets via environment, documented in setup
  • Output formatting considers channel constraints (check docs)