# GraphQL: Die moderne Query-Language für APIs

TL;DR / Management Summary Während REST (Artikel 823) für jede Ressource einen eigenen Endpunkt hat, nutzt GraphQL einen einzigen Endpunkt für alles. Der große Vorteil: Der Client bestimmt exakt, welche Felder er zurückbekommt. Ein Senior Admin nutzt GraphQL, um die Netzwerklast zwischen Microservices zu minimieren und um komplexe Abhängigkeiten (z.B. “Zeige mir alle VMs des Benutzers X inklusive deren Backups”) in einer einzigen Abfrage statt in fünf REST-Calls zu lösen.

# 1. Das GraphQL Konzept

Fragen, was man braucht.

Bei REST bekommen Sie oft zu viele Daten (Over-fetching) oder müssen mehrere Anfragen stellen (Under-fetching).

# Beispiel Query

{
  vm(id: 100) {
    name
    status
    storage {
      used_gb
    }
  }
}

# 2. Die Architektur (Schema & Resolvers)

Der Bauplan der Daten.

  1. Schema: Definiert die Typen und Felder (z.B. type VM { id: ID, name: String }).
  2. Resolvers: Die Funktionen im Hintergrund (z.B. in Python oder Go), welche die Daten aus Proxmox oder der SQL-DB holen.
  3. Mutations: Das Pendant zu POST/PUT – Befehle, die Daten ändern.

# 3. Deep Dive: Introspection

Die API, die sich selbst erklärt.

Eines der besten Features von GraphQL ist die Selbstdokumentation.

# 4. Day-2 Operations: Performance & N+1 Problem

Flaschenhälse im Code.

Ein häufiges Problem bei GraphQL: Der Server macht für jedes Feld eine eigene Datenbankabfrage (N+1 Problem).

# 5. Troubleshooting & “War Stories”

Wenn die Query zu groß wird.

# Top 3 Herausforderungen

  1. Symptom: Hohe Latenz bei komplexen Abfragen.

    • Ursache: “Circular Queries”. Ein User fragt die VM ab, die den Host abfragt, der wiederum alle VMs abfragt…
    • Lösung: Implementieren Sie eine Query Complexity Analysis, die zu tiefe Verschachtelungen blockiert.

  2. Symptom: Fehlende Fehlermeldungen (immer Status 200).

    • Ursache: GraphQL schickt Fehler oft im Body (errors Feld) statt via HTTP-Statuscode.
    • Lösung: Parsen Sie das JSON-Resultat immer auf das Vorhandensein des errors Keys.

  3. Symptom: Caching-Probleme.

    • Grund: Da alles über einen POST-Endpunkt läuft, funktionieren Standard-Browser-Caches nicht.

# “War Story”: Der “Auto-Complete” DoS

Ein Admin baute eine Suchfunktion für seine IPAM-Datenbank via GraphQL. Das Ereignis: Ein Entwickler nutzte die API für ein Auto-Complete Feld in der GUI. Bei jedem Tastendruck wurde die gesamte IP-Tabelle mit allen Verknüpfungen (VLANs, Switche, Kabel) abgefragt. Das Ergebnis: Die Datenbank war innerhalb von 5 Minuten überlastet. Lehre: Schränken Sie GraphQL-Queries durch Depth Limits und Rate Limiting ein. Die Flexibilität von GraphQL lädt dazu ein, ineffiziente Abfragen zu schreiben.

# 6. Monitoring & Reporting

Analytics.

# Apollo Studio / GraphDiff

Überwachen Sie die Nutzung Ihrer Felder:

# 7. Fazit & Empfehlung

GraphQL ist die ideale Wahl für Frontend-lastige Applikationen und komplexe Dashboards.

# Anhang: Vergleich GraphQL vs. REST

Merkmal REST GraphQL
Datenmenge Fix (Over-fetching) Flexibel (Präzise)
Endpunkte Viele Einer
Typisierung Optional (JSON) Strikt (Schema)
Caching Einfach (HTTP Level) Komplex (App Level)

# Referenzen