API Integration Fundamentals

Every useful OpenClaw module eventually talks to an external API. Weather, calendar, email, CRM, social media, AI models — the value of your agent comes from connecting intelligence to real-world data sources. The integration architecture determines whether those connections are reliable or fragile. I have seen modules that work perfectly in testing and break in production because the developer treated the API as a reliable function call. APIs are not function calls. They are network requests to services you do not control, subject to latency, rate limits, downtime, and breaking changes.

The integration layer sits between your logic and the external world. It handles three concerns that your business logic should never touch. Authentication — API keys, OAuth tokens, credential rotation. Error handling — retries, timeouts, rate limit backoff. Response normalization — converting the API vendor's response format into your module's internal schema. When these three concerns are isolated in the integration layer, swapping vendors (moving from one weather API to another) requires changing one file, not rewriting the module.

// Wrapper isolates auth, errors, and normalization
class CalendarAPI {
  private token: string;
  private baseUrl = 'https://api.calendar.example/v1';

  async getEvents(date: string): Promise<CalendarEvent[]> {
    const raw = await this.fetch(`/events?date=${date}`);
    return raw.items.map(this.normalize);  // vendor format → your format
  }

  private async fetch(path: string, retries = 3): Promise<any> {
    for (let i = 0; i < retries; i++) {
      try {
        const res = await fetch(this.baseUrl + path, {
          headers: { Authorization: `Bearer ${this.token}` },
        });
        if (res.status === 429) {
          await this.backoff(i);  // rate limit → exponential backoff
          continue;
        }
        if (!res.ok) throw new APIError(res.status, await res.text());
        return res.json();
      } catch (e) {
        if (i === retries - 1) throw e;
      }
    }
  }
}