Merge pull request 'feat: GraphQL und agentische KI (DE + EN)' (#8) from feature/graphql-agentische-ki into main

Reviewed-on: https://codeberg.org/gurix/markusgraf_ch/pulls/8

content/blog/graphql-agentische-ki/index.de.md

@@ -0,0 +1,77 @@
+---
+title: "Warum GraphQL APIs perfekt für agentische KI sind"
+date: 2026-05-10
+description: "GraphQL bringt Selbstdokumentation, flexible Abfragen und Schema-Introspection mit — genau das, was KI-Agenten brauchen, um APIs eigenständig zu verstehen und zu nutzen."
+translationKey: "graphql-agentische-ki"
+---
+
+Softwareentwicklung hatte lange ein stilles Grundprinzip: Man fragt sich, *wie Nutzer die Software verwenden sollen* — nicht wie sie sie verwenden wollen. Das hatte einen guten Grund. Software ist beim Anwender fix und fertig deployt. Sie muss Schnittstellen im Voraus definieren, weil sie sich zur Laufzeit nicht mehr anpassen kann. Der Entwickler trifft die Designentscheidungen, der Nutzer folgt.
+
+Dieses Prinzip beginnt sich grundlegend zu verschieben. Nicht durch eine neue Programmiersprache oder ein besseres Framework — sondern weil KI-Agenten zur Laufzeit selbst entscheiden können, wie sie mit einer Schnittstelle interagieren. Und genau hier kommt GraphQL ins Spiel.
+
+## Das Problem mit REST
+
+Beim traditionellen Design von API-Schnittstellen geht es darum, einem Consumer Daten und Funktionalität standardisiert zur Verfügung zu stellen. Im besten Fall als REST-Schnittstelle (Representational State Transfer) mit Standard-HTTP-Methoden für CRUD-Operationen. Die zentrale Frage beim Design ist dabei meist nicht, weshalb ein Client Daten beziehen will — sondern was man ihm zur Verfügung stellt und wie er diese Schnittstelle abfragen soll.
+
+Wer eine solche API anbinden will, ist auf Gedeih und Verderb darauf angewiesen, dass die Dokumentation des Betreibers aktuell und korrekt ist, dass Änderungen den Weg zum Consumer finden und dass die Schnittstelle brauchbar implementiert wurde. Die Realität zeigt oft ein ernüchterndes Bild: Standards und Konventionen werden nicht eingehalten, Daten die im UI sichtbar sind fehlen in der API, weil man schlicht nicht daran dachte, dass andere daran interessiert sein könnten.
+
+Ein weiteres strukturelles Problem: Für komplexere Fragestellungen muss die Schnittstelle mehrfach abgefragt werden. Wird beispielsweise ein Blog mit 50 Artikeln abgerufen, der auf mehrere Autoren referenziert, müssen wir entweder jeden Autor separat anfragen, alle Autoren einmal laden und filtern, oder hoffen, dass der Betreiber eine entsprechende Parametrisierung anbietet. Die clientseitige Implementierung ist jedenfalls nicht trivial — und mit jedem Versionswechsel der API darf man von vorne beginnen.
+
+## GraphQL: Das Schema kommt mit der Schnittstelle
+
+GraphQL bietet eine elegante Alternative. Daten werden nicht nur passiv geliefert, sondern über ein klar definiertes Schema aktiv abgefragt. Das Entscheidende: Das Schema ist nicht irgendwo in einem Wiki — es ist fest an die Implementierung geknüpft und kann jederzeit live abgefragt werden.
+
+Als echte Datenabfrage- und Manipulationssprache kann der Consumer selbst entscheiden, was er braucht. Etwas salopper formuliert: Der Client definiert, wie und was die Schnittstelle liefern soll.
+
+Sollen auf einer Startseite die neuesten drei Blogposts mit Titel und Datum dargestellt werden, lautet die Abfrage sinngemäss: *Gib mir drei Einträge mit Datum und Titel, sortiert nach Datum.* Sollen für eine Übersichtsseite alle Blogposts mit Titel, Untertitel, Autorenname und Kommentaranzahl geladen werden: *Gib mir die ersten 50, mit diesen Attributen.* Für beide Beispiele wird genau eine Anfrage gesendet, genau eine Antwort empfangen. Keine N+1-Probleme, keine Parallelrequests, kein Raten was die API wohl zurückgibt.
+
+Natürlich müssen die Relationen und Felder auch bei GraphQL implementiert sein. Moderne Bibliotheken wie Strawberry (Python) oder Apollo (JavaScript) machen das niederschwellig möglich.
+
+## Der eigentliche Gamechanger: KI-Agenten
+
+Für klassische Applikationen bietet GraphQL bereits handfeste Vorteile. Der eigentliche Gamechanger entfaltet sich aber erst im Zusammenspiel mit agentischer KI.
+
+Da das Schema jederzeit abrufbar ist, muss die Dokumentation nicht mehr separat mitgeliefert werden. Die Felder sind beschrieben und typisiert — ein KI-Agent kann das Schema selbst inspizieren und sich die optimale Abfrage eigenständig zusammenstellen. Kein manuelles Onboarding, kein Prompt-Engineering für jede neue API-Version.
+
+Das bedeutet auch: Ändert sich das Schema, muss der Agent nicht neu instruiert werden. Er schaut sich das Schema neu an, bemerkt selbst was sich verändert hat — und findet eigenständig einen neuen Weg. Was bei einer REST-Integration Stunden an Anpassungsarbeit bedeuten kann, erledigt der Agent im nächsten Request.
+
+## Ein konkretes Beispiel aus der Praxis
+
+Für mein [Wecker-Projekt](../wecker-raspberry-pi) gab es ursprünglich nur die Möglichkeit, Alarmzeiten manuell auf dem Server per Cronjob zu konfigurieren. Nicht sonderlich elegant, aber es funktionierte. Um den Wecker auch extern steuern zu können, implementierte ich eine einfache GraphQL-Schnittstelle, abgesichert mit einem API-Token.
+
+Mein Prompt an den Assistenten war denkbar knapp:
+
+> Kannst du per Tailnet auf den Host „wecker" zugreifen? Da sollte ein GraphQL-Endpunkt unter `http://wecker:8000` laufen, um den Wecker im Kinderzimmer zu steuern — versuch dich damit zu verbinden. API-Key ist `******`.
+
+Die Antwort:
+
+> Schema verstanden, und der bestehende Alarm ist auch schon sichtbar.
+>
+> **wecker GraphQL API:**
+> - `getAlarms` / `getAlarm(id)` — Alarme lesen
+> - `setAlarm(id?, cronExpression, command, isEnabled)` — Alarm erstellen oder updaten
+> - `deleteAlarm(id)` — löschen
+>
+> **Aktuell aktiver Alarm:**
+> - Cron: `45 6 * * 1-5` → Mo–Fr, 6:45 Uhr
+> - Command: `/usr/bin/python3 wecker.py` (auf dem Pi)
+> - Enabled: true
+>
+> Soll ich da was anpassen, oder willst du den Wecker von hier aus steuern können?
+
+Kein Handbuch, keine Endpoint-Liste, keine Dokumentation im Prompt. Der Agent hat das Schema selbst abgefragt, verstanden und sofort einsatzbereit gemeldet. Hätte ich die API im Nachhinein um neue Felder erweitert, hätte er das beim nächsten Zugriff automatisch bemerkt — ohne dass ich irgendetwas angepasst hätte.
+
+Von da an liess sich der Wecker bequem per Telegram-Nachricht steuern. Was vorher ein SSH-Aufruf auf dem Pi war, ist jetzt eine Unterhaltung.
+
+## Was das für API-Design bedeutet
+
+Das klassische Designprinzip — *was stelle ich dem Client zur Verfügung, und wie soll er es verwenden?* — ist nicht falsch. Es ist nur unvollständig geworden.
+
+In einer Welt mit agentischen KI-Clients verschiebt sich die relevante Frage:
+
+> Nicht mehr: *Wie soll der Consumer die Schnittstelle nutzen?*
+> Sondern: *Was kann ich anbieten — und warum?*
+
+Das **Wie** löst der Agent selbst. Was zählt, ist ein reichhaltiges, gut typisiertes Schema, das dem Agenten genug Kontext gibt, um eigenständig zu arbeiten. GraphQL ist dafür nicht die einzige Möglichkeit — aber eine, bei der Selbstbeschreibung von Anfang an eingebaut ist.
+
+Wer heute APIs für den Einsatz mit KI-Agenten entwirft, sollte GraphQL zumindest in Betracht ziehen. Nicht weil es trendy ist, sondern weil ein Agent, der sein Werkzeug selbst versteht, deutlich nützlicher ist als einer, dem man bei jeder Änderung erneut erklären muss, was er eigentlich tut.

content/blog/graphql-agentische-ki/index.en.md

@@ -0,0 +1,77 @@
+---
+title: "Why GraphQL APIs are perfect for agentic AI"
+date: 2026-05-10
+description: "GraphQL brings self-documentation, flexible queries and schema introspection — exactly what AI agents need to understand and use APIs autonomously."
+translationKey: "graphql-agentische-ki"
+---
+
+Software development has long had a quiet foundational principle: you ask yourself *how users should use the software* — not how they want to use it. That made sense. Software is deployed at the user's end, fixed and finished. It must define interfaces in advance, because it can no longer adapt at runtime. The developer makes the design decisions; the user follows.
+
+This principle is beginning to shift fundamentally. Not through a new programming language or a better framework — but because AI agents can now decide at runtime how to interact with an interface. And this is exactly where GraphQL comes in.
+
+## The Problem with REST
+
+Traditional API design is about providing consumers with data and functionality in a standardized way. Ideally as a REST interface (Representational State Transfer) with standard HTTP methods for CRUD operations. The central question in the design is usually not why a client wants data — but what you offer them and how they should query the interface.
+
+Anyone who wants to integrate such an API is completely dependent on the operator's documentation being current and correct, on changes reaching the consumer, and on the interface being implemented in a usable way. Reality often paints a sobering picture: standards and conventions go unenforced, data visible in the UI is missing from the API because nobody thought to expose it, and versioning is handled with all the grace of a filing cabinet falling down a staircase.
+
+There is also a structural problem: complex queries require multiple roundtrips. Fetching a blog with 50 articles referencing several authors means either requesting each author separately, loading all authors at once and filtering, or hoping the operator offers appropriate parameterization. The client-side implementation is non-trivial — and with every API version change, you get to start over.
+
+## GraphQL: The Schema Ships with the Interface
+
+GraphQL offers an elegant alternative. Data is not just passively delivered — it is actively queried through a clearly defined schema. The crucial point: the schema is not buried in some wiki. It is tightly coupled to the implementation and can be queried live at any time.
+
+As a proper data query and manipulation language, consumers can decide for themselves what they need. In slightly more casual terms: the client defines how and what the interface should deliver.
+
+To display the three most recent blog posts on a homepage with title and date, the query is essentially: *Give me three entries with date and title, sorted by date.* For an overview page with all blog posts including title, subtitle, author name, and comment count: *Give me the first 50, with these attributes.* For both examples, exactly one request is sent and exactly one response received. No N+1 problems, no parallel requests, no guessing what the API might return.
+
+Of course, the relations and fields need to be implemented in GraphQL as well. Modern libraries like Strawberry (Python) or Apollo (JavaScript) make this straightforward.
+
+## The Real Game Changer: AI Agents
+
+For classical applications, GraphQL already offers concrete advantages. But the real game changer only unfolds in combination with agentic AI.
+
+Since the schema can be retrieved at any time, documentation no longer needs to be provided separately. Fields are described and typed — an AI agent can inspect the schema itself and independently compose the optimal query. No manual onboarding, no prompt engineering for each new API version.
+
+This also means: when the schema changes, the agent does not need to be re-instructed. It inspects the schema anew, notices what changed — and finds its own path forward. What can mean hours of adaptation work for a REST integration, the agent handles in the next request.
+
+## A Concrete Example from Practice
+
+For my [alarm clock project](../wecker-raspberry-pi), the original way to configure alarm times was to manually edit cron jobs on the server. Not particularly elegant, but it worked. To enable external control of the alarm clock, I implemented a simple GraphQL interface secured with an API token.
+
+My prompt to the assistant was brief to the point of laziness:
+
+> Can you access the host "wecker" via Tailnet? There should be a GraphQL endpoint running at `http://wecker:8000` to control the alarm clock in the children's room — try connecting. API key is `******`.
+
+The response:
+
+> Schema understood, and the existing alarm is already visible.
+>
+> **wecker GraphQL API:**
+> - `getAlarms` / `getAlarm(id)` — read alarms
+> - `setAlarm(id?, cronExpression, command, isEnabled)` — create or update alarm
+> - `deleteAlarm(id)` — delete
+>
+> **Currently active alarm:**
+> - Cron: `45 6 * * 1-5` → Mon–Fri, 6:45 AM
+> - Command: `/usr/bin/python3 wecker.py` (on the Pi)
+> - Enabled: true
+>
+> Should I adjust something, or do you want to control the alarm clock from here?
+
+No manual, no endpoint list, no documentation in the prompt. The agent queried the schema itself, understood it, and was immediately ready to operate. Had I extended the API with new fields afterwards, it would have noticed automatically on the next access — without me changing anything.
+
+From that point on, the alarm clock could be conveniently controlled via Telegram message. What previously required an SSH call to the Pi is now a conversation.
+
+## What This Means for API Design
+
+The classic design principle — *what do I offer the client, and how should they use it?* — is not wrong. It has simply become incomplete.
+
+In a world with agentic AI clients, the relevant question shifts:
+
+> No longer: *How should the consumer use the interface?*
+> But rather: *What can I offer — and why?*
+
+The **how** is something the agent figures out itself. What matters is a rich, well-typed schema that gives the agent enough context to work autonomously. GraphQL is not the only way to achieve this — but it is one where self-description is built in from the start.
+
+Anyone designing APIs for use with AI agents today should at least consider GraphQL. Not because it is trendy, but because an agent that understands its own tools is considerably more useful than one that needs a new briefing every time something changes.