Seminar DatoCMS: Content Delivery API mit GraphQL

Das API-Seminar führt von der ersten sicheren Abfrage bis zu produktionsreifen Query-Bausteinen. Im Mittelpunkt stehen Schemaerkundung, Fragmente, Variablen, Filter, Lokalisierung, Entwürfe, Environments, Structured Text, Medien, Caching, Komplexität und Fehlerbehandlung.

Inhaltsübersicht

Kapitelinhaltsverzeichnis

• Lernziele und Einsatzbereiche
• Vorbereitung und Arbeitsweise
• Seminarinhalte
• Praktische Übungen und Anwendung

Lernziele und Einsatzbereiche

Kapitelinhaltsverzeichnis

• Kompetenzziele
• Typische Einsatzszenarien
• Abgrenzung und Schwerpunkt

Kompetenzziele

Die Inhalte sind auf unmittelbar anwendbare, prüfbare Kompetenzen ausgerichtet.

• GraphQL-Abfragen aus dem tatsächlichen DatoCMS-Schema ableiten.
• Wiederverwendbare Fragmente für Records, Blocks, Structured Text und Medien entwickeln.
• Draft-, Locale- und Environment-Kontexte sicher behandeln.
• Queries hinsichtlich Cache, Komplexität, Pagination und Fehlern produktionsreif gestalten.

Typische Einsatzszenarien

Das Seminar eignet sich insbesondere für die folgenden Projekt- und Betriebssituationen.

• Websites und Apps mit selektiver Inhaltsauslieferung.
• Statische Generierung und inkrementelle Aktualisierung.
• Preview- und Mehrsprachenanwendungen mit gemeinsamem Query-Bestand.

Abgrenzung und Schwerpunkt

Die fachliche Tiefe wird durch folgende Grenzen bewusst fokussiert.

• Keine vollständige Einführung in ein einzelnes Frontend-Framework.
• Schreiboperationen gehören in das CMA-Seminar.
• Netzwerk- und CDN-Grundlagen werden nur im Kontext der API behandelt.

Vorbereitung und Arbeitsweise

Kapitelinhaltsverzeichnis

• Zielgruppen
• Vorkenntnisse und Schulungsumgebung
• Didaktisches Vorgehen
• Qualitäts- und Abnahmekriterien

Zielgruppen

Frontend- und Full-Stack-Entwicklung, technische Architektur, Integrationsteams und DevOps mit Bezug zur Auslieferung.

Vorkenntnisse und Schulungsumgebung

Sichere Grundlagen in JavaScript oder TypeScript, HTTP und JSON. GraphQL-Grundkenntnisse sind hilfreich, werden jedoch systematisch aufgefrischt.

1. Schritt 1: Zugänge, Rollen und Schulungsprojekt vor Seminarbeginn kontrollieren.
2. Schritt 2: Beispieldaten, Assets, Quellmaterial oder Codebasis entsprechend dem Seminarthema bereitstellen.
3. Schritt 3: Ausgangszustand dokumentieren, damit Übungen wiederholt und Abweichungen eindeutig bewertet werden können.

Didaktisches Vorgehen

Kurze Fachblöcke werden unmittelbar mit Demonstrationen, geführten Arbeitsschritten, eigenständigen Laborphasen und kontrollierten Fehlerfällen verbunden.

1. Schritt 1: Ausgangsproblem und gewünschtes Sollverhalten präzisieren.
2. Schritt 2: Konfiguration oder Implementierung in kleinen, überprüfbaren Schritten ausführen.
3. Schritt 3: Normalfall, Grenzfall und mindestens einen Fehlerfall testen.
4. Schritt 4: Nachweis, Betriebsregel oder Checkliste aus dem Übungsergebnis ableiten.

Qualitäts- und Abnahmekriterien

• Konfigurationen und Arbeitsschritte sind reproduzierbar dokumentiert.
• Berechtigungen, Datenstände und Environments sind eindeutig voneinander getrennt.
• Positive und negative Testfälle besitzen ein erwartetes und nachvollziehbares Ergebnis.
• Fehlerzustände führen zu einer kontrollierten Diagnose und einem definierten Wiederanlauf.

Seminarinhalte

Kapitelinhaltsverzeichnis

• API-Zugriff und Token-Strategie
• Schemaerkundung und erste Query
• Fragmente und wiederverwendbare Query-Bausteine
• Filter, Sortierung und Pagination
• Lokalisierung, Entwürfe und Environments
• Structured Text, Blocks und Verknüpfungen
• Bilder, Videos und responsive Daten
• Caching, Cache Tags und Query-Komplexität
• Fehlerbehandlung und Betriebsdiagnose

API-Zugriff und Token-Strategie

Lesezugriffe werden nach veröffentlichten Inhalten, Entwürfen und Environments getrennt und ohne Geheimnisse im Browser aufgebaut.

1. Schritt 1: Anwendungsfall und benötigten Inhaltsstand festlegen.
2. Schritt 2: Passenden lesenden Token und Environment-Kontext auswählen.
3. Schritt 3: Zugriff serverseitig testen und Geheimnisablage prüfen.

Schemaerkundung und erste Query

Das automatisch bereitgestellte GraphQL-Schema wird aus Modellen, Feldern und Beziehungen systematisch gelesen.

1. Schritt 1: Einstiegsmodell und benötigte Felder im Schema identifizieren.
2. Schritt 2: Minimale Query mit Variablen erstellen.
3. Schritt 3: Antwort, Nullwerte und Typinformationen gegen das Modell prüfen.

Fragmente und wiederverwendbare Query-Bausteine

Fragmente reduzieren Inkonsistenzen zwischen Seiten, Komponenten und Teams.

1. Schritt 1: Gemeinsame Record- und Medienfelder bestimmen.
2. Schritt 2: Typisierte Fragmente pro Komponente formulieren.
3. Schritt 3: Doppelte Felder entfernen und Abhängigkeiten dokumentieren.

Filter, Sortierung und Pagination

Listenabfragen werden anhand fachlicher Filter, stabiler Sortierung und begrenzter Ergebnismengen gestaltet.

1. Schritt 1: Filterbedingungen und Sortierschlüssel aus dem Anwendungsfall ableiten.
2. Schritt 2: Variablen statt eingebetteter Werte verwenden.
3. Schritt 3: Pagination, Gesamtzahl und Randfälle mit leerem Ergebnis testen.

Lokalisierung, Entwürfe und Environments

Der Inhaltskontext wird explizit gesteuert, damit Preview, Übersetzung und Produktion keine Daten vermischen.

1. Schritt 1: Locale- und Fallback-Regel je Seite festlegen.
2. Schritt 2: Entwurfszugriff ausschließlich im geschützten Preview-Pfad aktivieren.
3. Schritt 3: Queries gegen primäres und Sandbox-Environment vergleichen.

Structured Text, Blocks und Verknüpfungen

Polymorphe Blocktypen und verknüpfte Records werden mit vollständigen Fragmenten abgefragt.

1. Schritt 1: Verwendete Blockmodelle und Links inventarisieren.
2. Schritt 2: Fragmente mit Typunterscheidung je Block formulieren.
3. Schritt 3: Unbekannte oder künftig ergänzte Blocktypen defensiv behandeln.

Bilder, Videos und responsive Daten

Medienfelder werden so abgefragt, dass Rendering, Barrierefreiheit und Bildoptimierung ausreichend Daten erhalten.

1. Schritt 1: Benötigte Bild-, Video- und Metadatenfelder definieren.
2. Schritt 2: Responsive Bildparameter auf Komponentenanforderungen abstimmen.
3. Schritt 3: Fehlende Assets und unvollständige Alt-Texte als Fehlerfall testen.

Caching, Cache Tags und Query-Komplexität

Abfragen werden messbar optimiert, statt nur nach subjektiver Geschwindigkeit beurteilt zu werden.

1. Schritt 1: Query-Kosten, Antwortgröße und Cache-Treffer protokollieren.
2. Schritt 2: Fragmente, Feldauswahl und Pagination optimieren.
3. Schritt 3: Cache- und Revalidierungsstrategie mit Änderungsereignissen verbinden.

Fehlerbehandlung und Betriebsdiagnose

Netzwerk-, HTTP-, GraphQL- und Datenfehler werden unterschieden und mit angemessenen Fallbacks behandelt.

1. Schritt 1: Fehlerklassen und Log-Felder definieren.
2. Schritt 2: Ungültigen Token, fehlerhafte Variable und Teilausfall simulieren.
3. Schritt 3: Fallback, Alarmierung und Nutzerreaktion prüfen.

Praktische Übungen und Anwendung

Kapitelinhaltsverzeichnis

• Produktliste mit Filtern und Pagination
• Landingpage mit polymorphen Blocks
• Preview- und Produktionsabfrage
• Optimierung einer zu teuren Query
• Prüf- und Abnahmekriterien

Produktliste mit Filtern und Pagination

Szenario: Eine Produktübersicht benötigt Kategorie, Status, Locale, Sortierung und Seitennavigation.

1. Schritt 1: Fachliche Filter und Ausgabefelder festlegen.
2. Schritt 2: Query und Variablen implementieren.
3. Schritt 3: Pagination und mehrere Locale-Werte testen.
4. Schritt 4: Antwortgröße und Query-Kosten dokumentieren.

Prüfkriterium: Die Query ist variablenbasiert, stabil sortiert, begrenzt und liefert auch bei leeren oder unvollständigen Daten ein definiertes Verhalten.

Landingpage mit polymorphen Blocks

Szenario: Eine Landingpage enthält Text, Bild, Call-to-Action und verknüpfte Teaser in Structured Text oder modularen Feldern.

1. Schritt 1: Blockmodelle und benötigte Felder inventarisieren.
2. Schritt 2: Typfragmente und gemeinsame Basisfelder erstellen.
3. Schritt 3: Testdaten mit allen Blocktypen abfragen.
4. Schritt 4: Unbekannten Blocktyp als defensiven Test ergänzen.

Prüfkriterium: Jeder Blocktyp besitzt ein passendes Fragment und kann ohne unkontrollierten Laufzeitfehler gerendert werden.

Preview- und Produktionsabfrage

Szenario: Dieselbe Seite wird veröffentlicht, als Entwurf geändert und in einer Sandbox weiterentwickelt.

1. Schritt 1: Drei Inhaltsstände vorbereiten.
2. Schritt 2: Kontextparameter und Tokenwege trennen.
3. Schritt 3: Antworten automatisiert vergleichen.
4. Schritt 4: Fehlkonfigurationen als Negativtest dokumentieren.

Prüfkriterium: Produktionsabfragen liefern ausschließlich freigegebene Inhalte; Preview und Sandbox sind getrennt und nachvollziehbar.

Optimierung einer zu teuren Query

Szenario: Eine absichtlich breite Abfrage überschreitet das vereinbarte Budget für Antwortgröße oder Komplexität.

1. Schritt 1: Baseline aus Laufzeit, Antwortgröße und Kosten erfassen.
2. Schritt 2: Überflüssige Felder und tiefe Beziehungen identifizieren.
3. Schritt 3: Query aufteilen oder mit Pagination begrenzen.
4. Schritt 4: Vorher-Nachher-Werte und Revalidierung testen.

Prüfkriterium: Die optimierte Variante erfüllt das Budget, behält die fachlichen Anforderungen und besitzt eine messbare Cache-Strategie.

Prüf- und Abnahmekriterien

Die Übungen werden nicht allein nach sichtbarer Funktion, sondern nach Reproduzierbarkeit, Sicherheit, Datenqualität und Betriebsfähigkeit bewertet.

• Der Ausgangszustand, die Änderung und der geprüfte Zielzustand sind dokumentiert.
• Mindestens ein Negativ- oder Störungstest wurde kontrolliert durchgeführt.
• Geheimnisse, produktive Daten und unbeteiligte Systeme wurden nicht in die Übungen einbezogen.
• Offene Punkte besitzen Priorität, verantwortliche Stelle und nächsten Prüftermin.