API-Gateway-Muster und Best Practices für moderne Anwendungen

Ein schlecht konzipiertes System wird zum Engpass und zum Single Point of Failure.

In diesem Leitfaden werden API-Gateway-Architekturmuster, Technologieauswahl und Best Practices für die Implementierung von Webanwendungen, ERP-Systemen und E-Commerce-Plattformen behandelt.

Wichtige Erkenntnisse

• API-Gateways zentralisieren übergreifende Belange (Authentifizierung, Ratenbegrenzung, Protokollierung), um Duplikate zwischen Diensten zu vermeiden – Die Ratenbegrenzung auf Gateway-Ebene schützt Backend-Dienste vor Verkehrsspitzen und Missbrauch – Leistungsschaltermuster verhindern kaskadierende Ausfälle, wenn nachgelagerte Dienste fehlerhaft sind
• Die API-Versionierung über das Gateway ermöglicht eine abwärtskompatible Weiterentwicklung Ihrer API-Oberfläche

---

Kern-Gateway-Muster

Muster 1: Routing anfordern

Das Gateway leitet Anfragen basierend auf dem URL-Pfad, den Headern oder anderen Anfrageattributen an den entsprechenden Back-End-Dienst weiter.

# Nginx as API gateway
upstream api_service {
    server api-1:3001;
    server api-2:3001;
}

upstream auth_service {
    server auth:9000;
}

upstream web_service {
    server web:3000;
}

server {
    listen 443 ssl;
    server_name api.example.com;

    location /api/v1/ {
        proxy_pass http://api_service;
    }

    location /auth/ {
        proxy_pass http://auth_service;
    }

    location / {
        proxy_pass http://web_service;
    }
}

Muster 2: Authentifizierung und Autorisierung

Zentralisieren Sie die Authentifizierung am Gateway, um die Implementierung in jedem Dienst zu vermeiden.

// NestJS middleware for JWT validation at the gateway level
@Injectable()
export class GatewayAuthMiddleware implements NestMiddleware {
  constructor(private readonly jwtService: JwtService) {}

  async use(req: Request, res: Response, next: NextFunction) {
    // Skip public endpoints
    if (this.isPublicEndpoint(req.path)) {
      return next();
    }

    const token = this.extractToken(req);
    if (!token) {
      throw new UnauthorizedException('Missing authentication token');
    }

    try {
      const payload = await this.jwtService.verifyAsync(token);
      req['user'] = payload;
      next();
    } catch {
      throw new UnauthorizedException('Invalid token');
    }
  }

  private extractToken(req: Request): string | undefined {
    // Check cookie first, then Authorization header
    return req.cookies?.ecosire_auth
      || req.headers.authorization?.replace('Bearer ', '');
  }

  private isPublicEndpoint(path: string): boolean {
    const publicPaths = ['/health', '/api/v1/products', '/api/v1/blog'];
    return publicPaths.some(p => path.startsWith(p));
  }
}

Muster 3: Ratenbegrenzung

// Rate limiting configuration per endpoint type
const rateLimits = {
  public: { windowMs: 60000, max: 100 },     // 100 req/min for public APIs
  authenticated: { windowMs: 60000, max: 500 }, // 500 req/min for authenticated users
  admin: { windowMs: 60000, max: 1000 },       // 1000 req/min for admin
  webhooks: { windowMs: 60000, max: 50 },       // 50 req/min for webhooks
};

Muster 4: Leistungsschalter

Wenn ein nachgelagerter Dienst ausfällt, verhindert der Leistungsschalter kaskadierende Ausfälle:

[Closed] --> (failures exceed threshold) --> [Open] --> (timeout expires) --> [Half-Open]
    ^                                                                            |
    |                                        (success)                           |
    +--------------------------------------------------------------------<-------+
    |                                        (failure)                           |
    |                                           +-------->  [Open]

Staaten:

• Geschlossen: Anfragen werden normal weitergeleitet. Verfolgen Sie die Anzahl der Fehler.
• Offen: Alle Anfragen schlagen sofort fehl, ohne dass der Dienst aufgerufen wird. Zwischengespeicherte/Fallback-Antwort zurückgeben.
• Halboffen: Eine Anfrage durchlassen. Wenn dies gelingt, schließen Sie den Stromkreis. Wenn dies fehlschlägt, öffnen Sie es erneut.

Muster 5: Antwort-Caching

# Cache GET responses for public endpoints
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:10m max_size=1g inactive=60m;

location /api/v1/products {
    proxy_pass http://api_service;
    proxy_cache api_cache;
    proxy_cache_valid 200 5m;
    proxy_cache_valid 404 1m;
    proxy_cache_key "$scheme$request_method$host$request_uri";
    add_header X-Cache-Status $upstream_cache_status;
}

---

API-Versionierungsstrategien

Empfehlung: URL-Pfadversionierung. Es ist das expliziteste, am besten debuggbare und am einfachsten zu routende Verfahren auf Gateway-Ebene.

Breaking vs. Non-Breaking Changes

---

Vergleich der Gateway-Technologie

Für die meisten KMUs: Nginx ist ausreichend. Es übernimmt Routing, SSL-Terminierung, Ratenbegrenzung und Caching mit einem Overhead von weniger als einer Millisekunde. Upgraden Sie auf Kong, wenn Sie erweiterte Plugin-Funktionen benötigen (OAuth2, Anforderungstransformation, Analyse).

---

Beobachtbarkeit am Gateway

Protokollierung anfordern

log_format gateway '$remote_addr - $remote_user [$time_local] '
                   '"$request" $status $body_bytes_sent '
                   '"$http_referer" "$http_user_agent" '
                   '$request_time $upstream_response_time '
                   '$http_x_request_id';

access_log /var/log/nginx/gateway.log gateway;

Metriksammlung

Verfolgen Sie diese Metriken auf Gateway-Ebene:

• Anfragerate nach Endpunkt, Methode und Statuscode
• Latenzverteilung (P50, P95, P99) nach Endpunkt
• Fehlerrate nach Endpunkt und Fehlertyp
• Ratenlimittreffer durch den Kunden
• Cache-Trefferquote nach Endpunkt
• Upstream-Antwortzeit im Vergleich zur Gesamtantwortzeit

---

Fehlerbehandlung am Gateway

Konsistente Fehlerreaktionen

Das Gateway sollte Fehlerantworten von verschiedenen Backend-Diensten normalisieren:

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The requested service is temporarily unavailable",
    "requestId": "req_abc123",
    "timestamp": "2026-03-16T14:32:01Z"
  }
}

Wiederholungs- und Timeout-Konfiguration

location /api/ {
    proxy_pass http://api_service;

    # Timeout configuration
    proxy_connect_timeout 5s;
    proxy_send_timeout 30s;
    proxy_read_timeout 30s;

    # Retry on connection errors only (not on 5xx)
    proxy_next_upstream error timeout;
    proxy_next_upstream_tries 2;

    # Custom error pages
    error_page 502 503 504 /api-error.json;
}

Anmutige Erniedrigung

Wenn ein unkritischer Back-End-Dienst ausfällt, kann das Gateway zwischengespeicherte Antworten oder Fallback-Daten bereitstellen, anstatt Fehler zurückzugeben:

---

Gateway-Sicherheitsmuster

Validierung anfordern

Überprüfen Sie die Anforderungsstruktur, bevor Sie sie an Backend-Dienste weiterleiten:

• Anfragen mit unbekannten Inhaltstypen ablehnen – Erzwingen Sie die maximale Größe des Anforderungstexts pro Endpunkt
• Validieren Sie die erforderlichen Header (API-Version, Inhaltstyp).
• Verdächtige Header entfernen (Hop-by-Hop-Header, serverinterne Header)

IP-Zulassungsliste für Admin-Endpunkte

location /api/admin/ {
    allow 203.0.113.0/24;  # Office IP range
    allow 10.0.0.0/8;      # Internal network
    deny all;

    proxy_pass http://api_service;
}

Transformation anfordern

Das Gateway kann vor der Weiterleitung Header hinzufügen, ändern oder entfernen:

location /api/ {
    proxy_pass http://api_service;

    # Add security headers
    proxy_set_header X-Request-ID $request_id;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;

    # Remove internal headers from responses
    proxy_hide_header X-Powered-By;
    proxy_hide_header Server;
}

---

Häufig gestellte Fragen

Benötigen wir ein API-Gateway für eine monolithische Anwendung?

Ja, aber eine einfachere. Selbst für einen Monolithen bietet Nginx als Reverse-Proxy SSL-Terminierung, Ratenbegrenzung, statische Dateibereitstellung und Sicherheitsheader. Für einen Monolithen benötigen Sie weder Kong noch AWS API Gateway, aber Sie benötigen etwas zwischen dem Internet und Ihrem Anwendungsserver.

Wie gehen wir mit einem API-Gateway-Failover um?

Führen Sie mehrere Gateway-Instanzen hinter einem Cloud-Load-Balancer (AWS ALB, Cloudflare) aus. Wenn eine Gateway-Instanz ausfällt, leitet der Load Balancer den Datenverkehr an fehlerfreie Instanzen weiter. Verwenden Sie für Nginx aktive Gesundheitsprüfungen und die automatische Entfernung fehlerhafter Upstreams.

Sollte das API-Gateway die Authentifizierung übernehmen oder sollte jeder Dienst dies tun?

Das Gateway sollte die Authentifizierung übernehmen (Überprüfung der Gültigkeit des Tokens). Einzelne Dienste sollten die Autorisierung übernehmen (überprüfen, ob der authentifizierte Benutzer die Berechtigung für die spezifische Aktion hat). Durch diese Trennung bleibt das Gateway leichtgewichtig und ermöglicht es den Diensten, differenzierte Entscheidungen zur Zugriffskontrolle zu treffen.

Wie gehen wir mit CORS am API-Gateway um?

Konfigurieren Sie CORS auf Gateway-Ebene, um die Duplizierung von CORS-Headern über mehrere Dienste hinweg zu vermeiden. Legen Sie Access-Control-Allow-Origin auf Ihre spezifischen Frontend-Domänen fest (verwenden Sie * niemals in der Produktion mit Anmeldeinformationen). Verarbeiten Sie Preflight-OPTIONS-Anfragen am Gateway, um die Belastung der Backend-Dienste zu reduzieren.

---

Was als nächstes kommt

Ein API-Gateway ist die Eingangstür zu Ihrer Infrastruktur. Kombinieren Sie es mit Überwachung für Sichtbarkeit, Sicherheitshärtung für Schutz und Lasttests für Kapazitätsplanung.

Kontaktieren Sie ECOSIRE für Beratung zur API-Architektur oder erkunden Sie unseren DevOps-Leitfaden für die vollständige Infrastruktur-Roadmap.

---

Veröffentlicht von ECOSIRE – Unterstützung von Unternehmen beim Aufbau einer skalierbaren API-Infrastruktur.