Produktionsreife APIs bauen: Der vollständige Engineering-Leitfaden

APIs sind Produkte

Die besten APIs der Welt — Stripe, Twilio, GitHub — werden oft als bessere Produkte zitiert als die eigene Benutzeroberfläche des Unternehmens. Das ist kein Zufall. Diese Unternehmen behandeln ihre APIs als erstklassige Produkte mit derselben Sorgfalt für die Entwicklererfahrung, die sie ihren UIs widmen.

Dieser Leitfaden behandelt die Engineering-Praktiken, die produktionsreife APIs vom Rest unterscheiden.

API-Designprinzipien

REST vs. GraphQL vs. gRPC

Wählen Sie das richtige Protokoll für Ihren Anwendungsfall:

Benennung und Struktur

Gutes API-Design ist langweilig. Es folgt etablierten Konventionen, damit Entwickler das Verhalten vorhersagen können, ohne die Dokumentation zu lesen.

✅ Gutes REST-API-Design:
GET    /api/v1/users              # Nutzer auflisten
POST   /api/v1/users              # Nutzer erstellen
GET    /api/v1/users/{id}         # Nutzer abrufen
PUT    /api/v1/users/{id}         # Nutzer ersetzen
PATCH  /api/v1/users/{id}         # Nutzer aktualisieren
DELETE /api/v1/users/{id}         # Nutzer löschen
GET    /api/v1/users/{id}/orders  # Bestellungen des Nutzers abrufen

❌ Häufige Fehler:
GET    /getUser?userId=123
POST   /api/createNewUser
GET    /api/fetchUserOrders/{userId}

Authentifizierung und Autorisierung

JWT-Best-Practices

import jwt from 'jsonwebtoken';

// ✅ Kurzlebige Access-Tokens + Refresh-Tokens
const ACCESS_TOKEN_EXPIRY = '15m';
const REFRESH_TOKEN_EXPIRY = '7d';

function generateTokenPair(userId: string) {
  const accessToken = jwt.sign(
    { sub: userId, type: 'access' },
    process.env.JWT_SECRET!,
    { expiresIn: ACCESS_TOKEN_EXPIRY }
  );

  const refreshToken = jwt.sign(
    { sub: userId, type: 'refresh', jti: crypto.randomUUID() },
    process.env.REFRESH_SECRET!,
    { expiresIn: REFRESH_TOKEN_EXPIRY }
  );

  return { accessToken, refreshToken };
}

Rate Limiting

Rate Limiting schützt Ihre API vor Missbrauch und sorgt für eine faire Nutzung. Implementieren Sie es auf mehreren Ebenen:

1. IP-Level-Limiting: DoS-Angriffe verhindern
2. Nutzer-Level-Limiting: Faire Nutzung durchsetzen
3. Endpoint-Level-Limiting: Teure Operationen erhalten niedrigere Limits

import { Ratelimit } from '@upstash/ratelimit';
import { Redis } from '@upstash/redis';

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(100, '1 m'), // 100 Anfragen pro Minute
  analytics: true,
});

export async function apiMiddleware(req: Request) {
  const identifier = getClientIdentifier(req);
  const { success, limit, remaining, reset } = await ratelimit.limit(identifier);

  if (!success) {
    return new Response('Too Many Requests', {
      status: 429,
      headers: {
        'X-RateLimit-Limit': limit.toString(),
        'X-RateLimit-Remaining': remaining.toString(),
        'X-RateLimit-Reset': new Date(reset).toISOString(),
        'Retry-After': Math.ceil((reset - Date.now()) / 1000).toString(),
      },
    });
  }
}

Fehlerbehandlung

Konsistente, informative Fehlerantworten sind das Markenzeichen einer großartigen API.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body is invalid",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "value": "not-an-email"
      }
    ],
    "requestId": "req_abc123",
    "docs": "https://api.eryon.ai/docs/errors/VALIDATION_ERROR"
  }
}

API-Versionierung

Brechen Sie niemals Ihre Konsumenten. Versionieren Sie Ihre API von Tag eins an.

Strategie: URL-Pfad-Versionierung (am einfachsten, am kompatibelsten)

/api/v1/users
/api/v2/users

Versionierungsregeln:

• Hauptversion (v1 → v2): Breaking Changes
• Nebenversion: Rückwärtskompatible Ergänzungen
• Deprecation-Richtlinie: 6 Monate vor Entfernung einer Version ankündigen

Die APIs, denen Entwickler vertrauen — und die zu Burggräben für Ihr Unternehmen werden — sind auf diesen Grundlagen aufgebaut. Jede Abkürzung beim API-Design kostet Sie das Zehnfache, wenn Sie sie mit Tausenden aktiver Integrationen korrigieren müssen.