Handling API Calls from Butlers: Event-Driven Architecture for Monitoring

Butlers need to make API calls. They need to fetch data from external services, send requests to third-party APIs, interact with databases, and communicate with other systems. But how should they do it? Direct API calls from each Butler? Or something more centralized?

I’ve been thinking about an event-driven approach: Butlers fire up an event requesting an API call, and the Butler core handles the actual HTTP request. The response comes back as another event. This way, we can monitor all outgoing traffic, implement consistent error handling, add retry logic, rate limiting, and more — all in one place.

The idea: Butlers don’t make API calls directly. They emit events. The Butler core listens, makes the actual HTTP request, and emits a response event. This centralizes monitoring, error handling, and API management — while keeping Butlers simple.

The Problem: Scattered API Calls

In a typical architecture, each Butler would make API calls directly:

This approach has several problems:

The Solution: Event-Driven API Calls

Instead of Butlers making API calls directly, they emit events. The Butler core listens to these events, makes the actual HTTP request, and emits a response event back to the Butler:

How It Works

Here’s how the event-driven API system would work:

Complete Data Flow

The following diagram shows the complete flow from a Butler mini app making an API request through the core system, including logging:

This flow ensures that all API calls go through the core system, enabling centralized monitoring, logging, and control. The logging happens asynchronously via a queue, so it doesn’t block the API response from reaching the Butler mini app.

The Request Event

When a Butler needs to make an API call, it emits a request event:

{
  type: "api.request",
  id: "req-123", // Unique request ID
  butler: "task-butler", // Which Butler made the request
  url: "https://api.example.com/tasks",
  method: "GET",
  headers: { "Authorization": "Bearer ..." },
  body: null,
  timeout: 5000,
  retries: 3
}

The Response Event

When the API call completes, Butler core emits a response event:

{
  type: "api.response",
  requestId: "req-123", // Matches the request ID
  butler: "task-butler",
  status: 200,
  data: { tasks: [...] },
  error: null,
  duration: 234 // milliseconds
}

The SDK

To make this easy for Butler developers, we’d provide an SDK:

// In Task Butler
import { api } from '@lifebutler/sdk';

// Make an API call
const response = await api.request({
  url: 'https://api.example.com/tasks',
  method: 'GET',
  headers: { 'Authorization': 'Bearer ...' }
});

// SDK handles:
// - Emitting request event
// - Waiting for response event
// - Returning response data
// - Throwing errors on failure

The SDK abstracts away the event system. Butler developers use a simple API interface, but under the hood, everything goes through events.

Benefits of This Approach

Monitoring Capabilities

With all API calls going through Butler core, we can monitor everything:

Implementation Considerations

This is still an idea, but here are some considerations for implementation:

Event System

We’d need a robust event system. Options include:

Request-Response Matching

The SDK needs to match request events with response events. Each request gets a unique ID, and the SDK waits for the matching response:

// SDK pseudocode
async function request(options) {
  const requestId = generateId();

  // Emit request event
  eventBus.emit('api.request', {
    id: requestId,
    ...options
  });

  // Wait for matching response event
  return new Promise((resolve, reject) => {
    eventBus.once(`api.response.${requestId}`, (response) => {
      if (response.error) {
        reject(response.error);
      } else {
        resolve(response.data);
      }
    });
  });
}

Error Handling

Butler core needs robust error handling:

The SDK

The SDK makes this easy for Butler developers. They don’t need to know about events — they just use a simple API:

Use Cases

Here are some scenarios where this approach shines:

Potential Challenges

This approach isn’t without challenges:

The Vision

The vision is simple: Butlers focus on their logic, not on making HTTP requests. They emit events saying “I need to call this API,” and Butler core handles the rest.

This centralizes all the hard parts: monitoring, error handling, rate limiting, retries, caching. Butler developers get these features automatically through the SDK. And we get full visibility into all API traffic from one place.

Butlers don’t make API calls. They emit events. Butler core handles HTTP, and everyone benefits: simpler Butler code, centralized monitoring, consistent error handling, easy feature addition.

Next Steps

This is still an idea, not a plan. But the concept is clear: an event-driven architecture for API calls, with an SDK that makes it easy for Butler developers.

If we build this, we’d start with:

This is a significant architectural change, but it could make API management much simpler and more powerful. We’ll see if this approach makes sense as we build out more Butlers and encounter more API management challenges.