Claude Code API Integration: REST-APIs in Minuten anbinden

Eine REST-API anzubinden kostet normalerweise einen halben Arbeitstag: Dokumentation lesen, Auth-Flow verstehen, TypeScript-Typen definieren, Wrapper schreiben, Fehlerbehandlung einbauen, Tests ergänzen. Claude Code komprimiert das auf unter eine Stunde — nicht weil es Boilerplate generiert, sondern weil es die Dokumentation selbst liest und versteht.

Dieser Artikel zeigt, wie die Claude Code API Integration in der Praxis funktioniert: von der GitHub-API bis zu Stripe, von OAuth bis zu automatisch generierten Tests.

1. Warum API-Integration mit Claude Code anders ist

Ein normaler Code-Generator nimmt deine Beschreibung und produziert generischen Fetch-Code. Claude Code macht etwas grundlegend anderes: Es liest die API-Dokumentation direkt, versteht die Authentifizierungsarchitektur und schreibt daraus typsichere Wrapper-Funktionen, die zum tatsächlichen API-Verhalten passen.

Das bedeutet konkret:

• Keine erfundenen Endpunkte. Claude Code liest die offizielle Doku — was es schreibt, existiert auch.
• Korrekte Auth-Flows. OAuth 2.0 mit PKCE ist anders als ein simpler Bearer-Token — Claude Code erkennt den Unterschied aus der Doku.
• Typen aus dem Schema. Wenn die API ein OpenAPI-Schema hat, leitet Claude Code die TypeScript-Interfaces direkt daraus ab.
• Kontextbewusstsein. Claude Code sieht dein bestehendes Projekt und schreibt den Wrapper so, dass er in deine bestehende Architektur passt — nicht irgendwie.

2. REST-API in 3 Schritten: GitHub-API anbinden

Das folgende Beispiel zeigt, wie du die GitHub REST API mit Claude Code in TypeScript anbindest — mit fetch-Wrapper und vollständigen Typen für Repositories und Pull Requests.

Schritt 1: Claude Code beauftragen

Starte Claude Code in deinem Projektverzeichnis und gib den Auftrag direkt:

claude "Integriere die GitHub REST API, ich brauche Repos und PRs als TypeScript-Typen mit fetch-Wrapper"

Claude Code liest daraufhin die GitHub-Dokumentation, analysiert deine Projektstruktur und schreibt einen vollständigen Client.

Schritt 2: Was Claude Code generiert

Das Ergebnis ist kein roher Fetch-Aufruf, sondern ein strukturierter Client:

// src/api/github.ts
interface GitHubRepo {
  id: number;
  name: string;
  full_name: string;
  private: boolean;
  default_branch: string;
  stargazers_count: number;
}

interface GitHubPR {
  number: number;
  title: string;
  state: 'open' | 'closed' | 'merged';
  user: { login: string };
  head: { ref: string; sha: string };
  base: { ref: string };
}

class GitHubClient {
  private baseUrl = 'https://api.github.com';
  private token: string;

  constructor(token: string) {
    this.token = token;
  }

  private async request<T>(path: string): Promise<T> {
    const res = await fetch(`${this.baseUrl}${path}`, {
      headers: {
        Authorization: `Bearer ${this.token}`,
        Accept: 'application/vnd.github+json',
        'X-GitHub-Api-Version': '2022-11-28',
      },
    });
    if (!res.ok) throw new Error(`GitHub API ${res.status}: ${path}`);
    return res.json();
  }

  async listRepos(org: string): Promise<GitHubRepo[]> {
    return this.request(`/orgs/${org}/repos?per_page=100`);
  }

  async listPRs(owner: string, repo: string): Promise<GitHubPR[]> {
    return this.request(`/repos/${owner}/${repo}/pulls?state=open`);
  }
}

Schritt 3: Sofort einsatzbereit

Claude Code legt auch die Initialisierung an und zeigt dir, wie du den Client verwendest:

import { GitHubClient } from './api/github';

const gh = new GitHubClient(process.env.GITHUB_TOKEN!);
const repos = await gh.listRepos('meine-organisation');
const prs = await gh.listPRs('meine-organisation', repos[0].name);

Was früher ein halber Tag Dokumentation-Lesen und Try-and-Error war, ist jetzt ein einzelner Prompt.

3. OAuth und API-Keys sicher implementieren

Die größte Fehlerquelle bei der Claude Code REST API-Integration ist nicht der Endpunkt — es ist die Authentifizierung. Falsch gespeicherte Keys, fehlende Token-Rotation, Hardcoding im Code: Claude Code schreibt das von Anfang an richtig.

Sicheres .env-Handling

Claude Code schreibt kein einziges hardcoded Secret. Stattdessen generiert es strukturiertes .env-Handling mit Validierung:

// src/config/env.ts
function requireEnv(key: string): string {
  const value = process.env[key];
  if (!value) throw new Error(`Missing required env var: ${key}`);
  return value;
}

export const config = {
  github: {
    token: requireEnv('GITHUB_TOKEN'),
  },
  stripe: {
    secretKey: requireEnv('STRIPE_SECRET_KEY'),
    webhookSecret: requireEnv('STRIPE_WEBHOOK_SECRET'),
  },
};

Die zugehörige .env.example generiert Claude Code ebenfalls — mit Kommentaren, wo du die Keys herbekommst.

OAuth 2.0 Token-Refresh

Für APIs mit kurzlebigen Access Tokens schreibt Claude Code automatisch die Refresh-Logik:

class OAuthClient {
  private accessToken: string;
  private refreshToken: string;
  private expiresAt: number;

  private async refreshIfNeeded(): Promise<void> {
    // Token 60 Sekunden vor Ablauf erneuern
    if (Date.now() >= this.expiresAt - 60_000) {
      const tokens = await this.fetchNewTokens(this.refreshToken);
      this.accessToken = tokens.access_token;
      this.expiresAt = Date.now() + tokens.expires_in * 1000;
    }
  }

  async request(path: string) {
    await this.refreshIfNeeded();
    // ... request logic
  }
}

4. Error-Handling und Retry-Logik

API-Fehler sind unvermeidlich: Rate Limits, temporäre Server-Fehler, Timeouts. Claude Code schreibt keine naive Fehlerbehandlung mit einem einzigen try-catch — es implementiert robuste Patterns, die in Produktion funktionieren.

Exponential Backoff

async function fetchWithRetry<T>(
  fn: () => Promise<T>,
  options = { maxRetries: 3, baseDelay: 1000 }
): Promise<T> {
  let lastError: Error;

  for (let attempt = 0; attempt < options.maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      lastError = err as Error;

      // Nicht-retryable Fehler sofort werfen
      if (err instanceof ApiError && err.status < 500 && err.status !== 429) {
        throw err;
      }

      // Exponential Backoff mit Jitter
      const delay = options.baseDelay * Math.pow(2, attempt)
        + Math.random() * 100;
      await sleep(delay);
    }
  }

  throw lastError!;
}

Rate Limiting und Timeout

// Rate-Limit-Header auswerten
async function handleRateLimit(response: Response): Promise<void> {
  if (response.status === 429) {
    const retryAfter = response.headers.get('Retry-After');
    const delay = retryAfter ? parseInt(retryAfter) * 1000 : 60_000;
    await sleep(delay);
  }
}

// Request-Timeout
async function fetchWithTimeout(
  url: string,
  options: RequestInit,
  timeoutMs = 10_000
): Promise<Response> {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);

  try {
    return await fetch(url, { ...options, signal: controller.signal });
  } finally {
    clearTimeout(timeoutId);
  }
}

Claude Code kombiniert diese Patterns in einem einzigen, produktionsreifen Request-Handler — du musst sie nicht manuell zusammenbauen.

5. API-Tests automatisch schreiben

Gute Claude Code API-Integration endet nicht beim Wrapper. Claude Code generiert auch die Tests — mit Mock-Server, Happy-Path, Edge-Cases und Fehlerszenarien.

Jest-Tests für den API-Wrapper

// tests/github.test.ts
import { GitHubClient } from '../src/api/github';

// Mock fetch global
global.fetch = jest.fn();

describe('GitHubClient', () => {
  let client: GitHubClient;

  beforeEach(() => {
    client = new GitHubClient('test-token');
    jest.clearAllMocks();
  });

  describe('listRepos', () => {
    it('returns repos for valid org', async () => {
      (fetch as jest.Mock).mockResolvedValueOnce({
        ok: true,
        json: async () => [{ id: 1, name: 'my-repo', full_name: 'org/my-repo' }],
      });

      const repos = await client.listRepos('org');
      expect(repos).toHaveLength(1);
      expect(repos[0].name).toBe('my-repo');
    });

    it('throws on API error', async () => {
      (fetch as jest.Mock).mockResolvedValueOnce({ ok: false, status: 404 });
      await expect(client.listRepos('nonexistent')).rejects.toThrow('GitHub API 404');
    });

    it('sets correct auth header', async () => {
      (fetch as jest.Mock).mockResolvedValueOnce({ ok: true, json: async () => [] });
      await client.listRepos('org');

      expect(fetch).toHaveBeenCalledWith(
        expect.any(String),
        expect.objectContaining({
          headers: expect.objectContaining({
            Authorization: 'Bearer test-token',
          }),
        })
      );
    });
  });
});

Claude Code schreibt nicht nur den Happy-Path — es denkt Edge-Cases durch: Was passiert bei leerer Liste? Bei Rate-Limit-Antwort? Bei Netzwerk-Timeout? All das landet als eigenständiger Test.

6. Zeitvergleich: API-Integration mit vs. ohne Claude Code

Das folgende Beispiel basiert auf einer vollständigen Stripe-API-Integration — Payment Intent erstellen, Webhooks verarbeiten, Customer-Verwaltung, typsichere Interfaces für alle relevanten Objekte.

Der Zeitgewinn ist am größten bei APIs mit komplexer Authentifizierung oder umfangreichem Schema. Eine einfache REST-API ohne Auth spart weniger, eine komplexe OAuth 2.0-Integration mit PKCE spart mehr als im Beispiel.

Mehr über die Integration von Claude Code in TypeScript-Projekte: Claude Code mit TypeScript: typsichere Entwicklung. Und wenn etwas beim API-Wrapper nicht funktioniert: Claude Code Debugging: Fehler systematisch finden.