API Integration Patterns für Automation

Meta-Description: Robuste API Integrationen. Retry Logic, Rate Limiting, Webhooks und Error Handling für zuverlässige Automatisierung.

Keywords: API Integration, Retry Logic, Rate Limiting, Webhooks, Error Handling, REST API, HTTP Client

Einführung

Zuverlässige API-Integrationen sind das Fundament jeder Automation. Retry Logic, Rate Limiting, Circuit Breaker – diese Patterns machen den Unterschied zwischen fragilen und robusten Systemen.

API Client Architecture

┌─────────────────────────────────────────────────────────────┐
│              ROBUST API CLIENT                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Request Flow:                                              │
│                                                             │
│  Application                                                │
│       ↓                                                    │
│  Rate Limiter (Throttle Requests)                          │
│       ↓                                                    │
│  Retry Handler (Exponential Backoff)                       │
│       ↓                                                    │
│  Circuit Breaker (Fail Fast)                               │
│       ↓                                                    │
│  HTTP Client (Axios/Fetch)                                 │
│       ↓                                                    │
│  Response Handler (Parse/Validate)                         │
│       ↓                                                    │
│  Application                                                │
│                                                             │
│  Cross-Cutting Concerns:                                    │
│  ├── Logging                                               │
│  ├── Metrics                                               │
│  └── Caching                                               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Base API Client

import axios, { AxiosInstance, AxiosRequestConfig, AxiosError } from 'axios';

interface ApiClientConfig {
  baseURL: string;
  timeout?: number;
  headers?: Record<string, string>;
  retries?: number;
  retryDelay?: number;
  rateLimit?: {
    maxRequests: number;
    windowMs: number;
  };
}

class ApiClient {
  private client: AxiosInstance;
  private config: Required<ApiClientConfig>;
  private requestTimestamps: number[] = [];

  constructor(config: ApiClientConfig) {
    this.config = {
      timeout: 30000,
      headers: {},
      retries: 3,
      retryDelay: 1000,
      rateLimit: { maxRequests: 100, windowMs: 60000 },
      ...config
    };

    this.client = axios.create({
      baseURL: this.config.baseURL,
      timeout: this.config.timeout,
      headers: this.config.headers
    });

    this.setupInterceptors();
  }

  private setupInterceptors() {
    // Request Interceptor
    this.client.interceptors.request.use(
      async (config) => {
        await this.waitForRateLimit();
        this.recordRequest();

        console.log(`[API] ${config.method?.toUpperCase()} ${config.url}`);
        return config;
      },
      (error) => Promise.reject(error)
    );

    // Response Interceptor
    this.client.interceptors.response.use(
      (response) => {
        console.log(`[API] Response: ${response.status}`);
        return response;
      },
      async (error: AxiosError) => {
        const config = error.config as AxiosRequestConfig & { _retryCount?: number };

        if (!config || !this.shouldRetry(error, config._retryCount || 0)) {
          return Promise.reject(this.formatError(error));
        }

        config._retryCount = (config._retryCount || 0) + 1;

        const delay = this.calculateDelay(config._retryCount);
        console.log(`[API] Retry ${config._retryCount}/${this.config.retries} after ${delay}ms`);

        await this.sleep(delay);
        return this.client.request(config);
      }
    );
  }

  private shouldRetry(error: AxiosError, retryCount: number): boolean {
    if (retryCount >= this.config.retries) return false;

    // Retry bei Netzwerkfehlern
    if (!error.response) return true;

    // Retry bei bestimmten Status Codes
    const retryableStatuses = [408, 429, 500, 502, 503, 504];
    return retryableStatuses.includes(error.response.status);
  }

  private calculateDelay(retryCount: number): number {
    // Exponential Backoff mit Jitter
    const baseDelay = this.config.retryDelay;
    const exponentialDelay = baseDelay * Math.pow(2, retryCount - 1);
    const jitter = Math.random() * 1000;
    return exponentialDelay + jitter;
  }

  private async waitForRateLimit(): Promise<void> {
    const now = Date.now();
    const windowStart = now - this.config.rateLimit.windowMs;

    // Alte Timestamps entfernen
    this.requestTimestamps = this.requestTimestamps.filter(t => t > windowStart);

    if (this.requestTimestamps.length >= this.config.rateLimit.maxRequests) {
      const oldestRequest = this.requestTimestamps[0];
      const waitTime = oldestRequest + this.config.rateLimit.windowMs - now;

      if (waitTime > 0) {
        console.log(`[API] Rate limit reached, waiting ${waitTime}ms`);
        await this.sleep(waitTime);
      }
    }
  }

  private recordRequest() {
    this.requestTimestamps.push(Date.now());
  }

  private formatError(error: AxiosError): Error {
    if (error.response) {
      return new Error(
        `API Error: ${error.response.status} - ${JSON.stringify(error.response.data)}`
      );
    }
    if (error.request) {
      return new Error(`Network Error: ${error.message}`);
    }
    return error;
  }

  private sleep(ms: number): Promise<void> {
    return new Promise(resolve => setTimeout(resolve, ms));
  }

  // Public Methods
  async get<T>(url: string, config?: AxiosRequestConfig): Promise<T> {
    const response = await this.client.get<T>(url, config);
    return response.data;
  }

  async post<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T> {
    const response = await this.client.post<T>(url, data, config);
    return response.data;
  }

  async put<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T> {
    const response = await this.client.put<T>(url, data, config);
    return response.data;
  }

  async delete<T>(url: string, config?: AxiosRequestConfig): Promise<T> {
    const response = await this.client.delete<T>(url, config);
    return response.data;
  }
}

Circuit Breaker Pattern

enum CircuitState {
  CLOSED = 'CLOSED',     // Normal Operation
  OPEN = 'OPEN',         // Failing, block requests
  HALF_OPEN = 'HALF_OPEN' // Testing recovery
}

interface CircuitBreakerConfig {
  failureThreshold: number;
  successThreshold: number;
  timeout: number;
}

class CircuitBreaker {
  private state: CircuitState = CircuitState.CLOSED;
  private failureCount = 0;
  private successCount = 0;
  private lastFailureTime?: number;
  private config: CircuitBreakerConfig;

  constructor(config: Partial<CircuitBreakerConfig> = {}) {
    this.config = {
      failureThreshold: 5,
      successThreshold: 2,
      timeout: 30000,
      ...config
    };
  }

  async execute<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === CircuitState.OPEN) {
      if (this.shouldAttemptReset()) {
        this.state = CircuitState.HALF_OPEN;
      } else {
        throw new Error('Circuit breaker is OPEN');
      }
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  private shouldAttemptReset(): boolean {
    return (
      this.lastFailureTime !== undefined &&
      Date.now() - this.lastFailureTime >= this.config.timeout
    );
  }

  private onSuccess() {
    if (this.state === CircuitState.HALF_OPEN) {
      this.successCount++;

      if (this.successCount >= this.config.successThreshold) {
        this.reset();
      }
    }

    this.failureCount = 0;
  }

  private onFailure() {
    this.failureCount++;
    this.lastFailureTime = Date.now();

    if (this.state === CircuitState.HALF_OPEN) {
      this.state = CircuitState.OPEN;
      this.successCount = 0;
    } else if (this.failureCount >= this.config.failureThreshold) {
      this.state = CircuitState.OPEN;
    }
  }

  private reset() {
    this.state = CircuitState.CLOSED;
    this.failureCount = 0;
    this.successCount = 0;
    this.lastFailureTime = undefined;
  }

  getState(): CircuitState {
    return this.state;
  }
}

// Verwendung
const circuitBreaker = new CircuitBreaker({ failureThreshold: 3 });

async function callExternalApi() {
  return circuitBreaker.execute(async () => {
    return apiClient.get('/data');
  });
}

Webhook Handler

import { createHmac, timingSafeEqual } from 'crypto';

interface WebhookConfig {
  secret: string;
  tolerance: number;  // Sekunden
}

class WebhookHandler {
  private config: WebhookConfig;
  private handlers: Map<string, (data: any) => Promise<void>> = new Map();

  constructor(config: WebhookConfig) {
    this.config = config;
  }

  register(event: string, handler: (data: any) => Promise<void>) {
    this.handlers.set(event, handler);
  }

  async handle(
    payload: string,
    signature: string,
    timestamp: string
  ): Promise<void> {
    // 1. Signature validieren
    if (!this.verifySignature(payload, signature, timestamp)) {
      throw new Error('Invalid webhook signature');
    }

    // 2. Timestamp validieren (Replay Attack Prevention)
    if (!this.verifyTimestamp(timestamp)) {
      throw new Error('Webhook timestamp too old');
    }

    // 3. Event verarbeiten
    const event = JSON.parse(payload);
    const handler = this.handlers.get(event.type);

    if (handler) {
      await handler(event.data);
    } else {
      console.warn(`No handler for event type: ${event.type}`);
    }
  }

  private verifySignature(
    payload: string,
    signature: string,
    timestamp: string
  ): boolean {
    const signedPayload = `${timestamp}.${payload}`;
    const expectedSignature = createHmac('sha256', this.config.secret)
      .update(signedPayload)
      .digest('hex');

    const sigBuffer = Buffer.from(signature);
    const expectedBuffer = Buffer.from(`sha256=${expectedSignature}`);

    return sigBuffer.length === expectedBuffer.length &&
           timingSafeEqual(sigBuffer, expectedBuffer);
  }

  private verifyTimestamp(timestamp: string): boolean {
    const webhookTime = parseInt(timestamp, 10) * 1000;
    const now = Date.now();
    const tolerance = this.config.tolerance * 1000;

    return Math.abs(now - webhookTime) <= tolerance;
  }
}

// Express Route
import express from 'express';

const app = express();
const webhookHandler = new WebhookHandler({
  secret: process.env.WEBHOOK_SECRET!,
  tolerance: 300  // 5 Minuten
});

// Webhook Events registrieren
webhookHandler.register('order.created', async (data) => {
  await processNewOrder(data);
});

webhookHandler.register('payment.completed', async (data) => {
  await completePayment(data);
});

// Webhook Endpoint
app.post('/webhooks',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-webhook-signature'] as string;
    const timestamp = req.headers['x-webhook-timestamp'] as string;

    try {
      await webhookHandler.handle(
        req.body.toString(),
        signature,
        timestamp
      );

      res.status(200).send('OK');
    } catch (error) {
      console.error('Webhook error:', error);
      res.status(400).send('Invalid webhook');
    }
  }
);

Pagination Handler

interface PaginatedResponse<T> {
  data: T[];
  pagination: {
    page: number;
    pageSize: number;
    total: number;
    hasMore: boolean;
  };
}

async function* paginatedFetch<T>(
  apiClient: ApiClient,
  endpoint: string,
  pageSize: number = 100
): AsyncGenerator<T[], void, unknown> {
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await apiClient.get<PaginatedResponse<T>>(
      `${endpoint}?page=${page}&pageSize=${pageSize}`
    );

    yield response.data;

    hasMore = response.pagination.hasMore;
    page++;
  }
}

// Cursor-based Pagination
async function* cursorPaginatedFetch<T>(
  apiClient: ApiClient,
  endpoint: string,
  limit: number = 100
): AsyncGenerator<T[], void, unknown> {
  let cursor: string | null = null;

  while (true) {
    const url = cursor
      ? `${endpoint}?cursor=${cursor}&limit=${limit}`
      : `${endpoint}?limit=${limit}`;

    const response = await apiClient.get<{
      data: T[];
      nextCursor: string | null;
    }>(url);

    yield response.data;

    if (!response.nextCursor) break;
    cursor = response.nextCursor;
  }
}

// Verwendung
async function fetchAllProducts() {
  const allProducts: Product[] = [];

  for await (const products of paginatedFetch<Product>(apiClient, '/products')) {
    allProducts.push(...products);
    console.log(`Fetched ${allProducts.length} products so far`);
  }

  return allProducts;
}

Response Caching

interface CacheEntry<T> {
  data: T;
  expiresAt: number;
  etag?: string;
}

class ResponseCache {
  private cache: Map<string, CacheEntry<any>> = new Map();
  private defaultTTL: number;

  constructor(defaultTTL: number = 60000) {
    this.defaultTTL = defaultTTL;
  }

  set<T>(key: string, data: T, ttl?: number, etag?: string) {
    this.cache.set(key, {
      data,
      expiresAt: Date.now() + (ttl || this.defaultTTL),
      etag
    });
  }

  get<T>(key: string): CacheEntry<T> | null {
    const entry = this.cache.get(key);

    if (!entry) return null;

    if (Date.now() > entry.expiresAt) {
      this.cache.delete(key);
      return null;
    }

    return entry;
  }

  invalidate(pattern: string | RegExp) {
    for (const key of this.cache.keys()) {
      if (typeof pattern === 'string' ? key.includes(pattern) : pattern.test(key)) {
        this.cache.delete(key);
      }
    }
  }
}

// Mit ETag Support
async function fetchWithCache<T>(
  apiClient: ApiClient,
  url: string,
  cache: ResponseCache
): Promise<T> {
  const cacheKey = url;
  const cached = cache.get<T>(cacheKey);

  const headers: Record<string, string> = {};

  if (cached?.etag) {
    headers['If-None-Match'] = cached.etag;
  }

  try {
    const response = await apiClient.get<T>(url, { headers });
    const etag = (response as any).headers?.etag;

    cache.set(cacheKey, response, undefined, etag);
    return response;
  } catch (error: any) {
    if (error.response?.status === 304 && cached) {
      return cached.data;
    }
    throw error;
  }
}

Fazit

Robuste API Integrationen brauchen:

1. Retry Logic: Exponential Backoff mit Jitter
2. Rate Limiting: Client-seitige Throttling
3. Circuit Breaker: Fail Fast bei Ausfällen
4. Caching: Reduziert Last und Latenz

Production-ready von Anfang an.

Bildprompts

1. "API calls with retry arrows showing resilience, error recovery"
2. "Circuit breaker switch between services, fail fast concept"
3. "Rate limiter queue with request tickets, throttling visualization"

Quellen

• Axios Documentation
• Circuit Breaker Pattern
• API Rate Limiting Best Practices
• Webhook Security