Seminar CrafterCMS – REST, GraphQL und JavaScript SDK

Dieses praxisorientierte Seminar verbindet fachliche Einordnung, nachvollziehbare Konfigurationsschritte und kontrollierte Übungen an einer durchgängigen CrafterCMS-Laborumgebung. Ein stabiler, sicherer und testbarer API-Zugriff wird für typische Content-, Listen-, Such- und Medienfälle entwickelt.

Inhaltsverzeichnis

1. Zielsetzung
2. 1. API-Strategie und Content-Vertrag
3. 2. REST-basierter Content Retrieval
4. 3. GraphQL für gezielte Abfragen
5. 4. JavaScript SDK und typisierte Zugriffsschicht
6. 5. Suche, Medien und statische Ressourcen
7. 6. Sicherheit, Caching und Fehlerverträge
8. 7. Contract Tests und API-Betrieb
9. Praxisprojekt und Qualitätssicherung
10. Zielgruppe und Voraussetzungen
11. Didaktik und Arbeitsweise

Zielsetzung

Ein stabiler, sicherer und testbarer API-Zugriff wird für typische Content-, Listen-, Such- und Medienfälle entwickelt. Die einzelnen Arbeitsschritte werden jeweils mit einem definierten Ausgangszustand, einem erwarteten Prüfergebnis und einer dokumentierten Korrekturmöglichkeit durchgeführt.

Seminarinhalte

1. API-Strategie und Content-Vertrag

Datenbedarf, Abfrageform und Stabilitätsanforderungen werden vor der Implementierung verbindlich festgelegt. Zu jedem Arbeitsschritt wird geprüft, ob Konfiguration, Inhalt und Betriebszustand dem erwarteten Ergebnis entsprechen.

Schritt-für-Schritt

1. Schritt 1: Nutzerfälle und benötigte Content-Strukturen erfassen. Prüfpunkt: Abfragen folgen konkreten Anforderungen.
2. Schritt 2: Pflichtfelder, optionale Felder und Beziehungen definieren. Prüfpunkt: Vertrag ist eindeutig.
3. Schritt 3: REST, GraphQL oder SDK je Fall auswählen. Prüfpunkt: Technikwahl ist begründet.
4. Schritt 4: Versionierungs- und Kompatibilitätsregel festlegen. Prüfpunkt: Clients können kontrolliert weiterentwickelt werden.
5. Schritt 5: Beispielantworten als Contract Fixture speichern. Prüfpunkt: Erwartung ist automatisiert prüfbar.

2. REST-basierter Content Retrieval

Seiten, Komponenten und Metadaten werden über klar begrenzte REST-Aufrufe abgerufen. Zu jedem Arbeitsschritt wird geprüft, ob Konfiguration, Inhalt und Betriebszustand dem erwarteten Ergebnis entsprechen.

Schritt-für-Schritt

1. Schritt 1: Delivery-Endpunkt und Site-Kontext konfigurieren. Prüfpunkt: Client nutzt die richtige Umgebung.
2. Schritt 2: Einzelinhalt und Baumstruktur abrufen. Prüfpunkt: Pfad- und Hierarchiedaten sind verfügbar.
3. Schritt 3: Beziehungen und eingebettete Komponenten kontrolliert auflösen. Prüfpunkt: Client vermeidet unnötige Folgeaufrufe.
4. Schritt 4: Nicht gefundene, ungültige und gesperrte Inhalte behandeln. Prüfpunkt: Fehlerzustände sind eindeutig.
5. Schritt 5: Antwortgröße und Latenz messen. Prüfpunkt: Abfrage ist für Produktion geeignet.

3. GraphQL für gezielte Abfragen

GraphQL wird für variabel zusammengesetzte Listen, Beziehungen und typisierte Daten eingesetzt. Zu jedem Arbeitsschritt wird geprüft, ob Konfiguration, Inhalt und Betriebszustand dem erwarteten Ergebnis entsprechen.

Schritt-für-Schritt

1. Schritt 1: Schema und verfügbare Typen erkunden. Prüfpunkt: Abfrage basiert auf realem Modell.
2. Schritt 2: Query mit ausgewählten Feldern und Filtern erstellen. Prüfpunkt: Nur benötigte Daten werden übertragen.
3. Schritt 3: Verschachtelte Beziehungen mit kontrollierter Tiefe laden. Prüfpunkt: Komplexität bleibt beherrscht.
4. Schritt 4: Variablen, Fragmente und Wiederverwendung einsetzen. Prüfpunkt: Queries sind wartbar.
5. Schritt 5: Fehler in Daten und GraphQL-Fehlern getrennt behandeln. Prüfpunkt: Client reagiert korrekt.

4. JavaScript SDK und typisierte Zugriffsschicht

SDK-Aufrufe werden in eine zentrale, testbare und typisierte Anwendungsbibliothek gekapselt. Zu jedem Arbeitsschritt wird geprüft, ob Konfiguration, Inhalt und Betriebszustand dem erwarteten Ergebnis entsprechen.

Schritt-für-Schritt

1. Schritt 1: SDK initialisieren und Umgebungswerte externalisieren. Prüfpunkt: Konfiguration ist reproduzierbar.
2. Schritt 2: Servicefunktionen für Seiten, Listen und Suche erstellen. Prüfpunkt: Frontend nutzt eine einheitliche Schnittstelle.
3. Schritt 3: TypeScript-Typen aus dem Content-Vertrag ableiten. Prüfpunkt: Fehler werden früh sichtbar.
4. Schritt 4: Retry, Timeout und Abbruch integrieren. Prüfpunkt: Netzwerkfehler sind kontrolliert.
5. Schritt 5: Services mit Mocks und Fixtures testen. Prüfpunkt: Zugriffsschicht ist unabhängig prüfbar.

5. Suche, Medien und statische Ressourcen

Content Retrieval wird um Suchfälle und effiziente Asset-Auslieferung ergänzt. Zu jedem Arbeitsschritt wird geprüft, ob Konfiguration, Inhalt und Betriebszustand dem erwarteten Ergebnis entsprechen.

Schritt-für-Schritt

1. Schritt 1: Suchquery mit Filtern und Paging ausführen. Prüfpunkt: Ergebnis entspricht der Nutzeraufgabe.
2. Schritt 2: Facetten oder Sortierung verarbeiten. Prüfpunkt: Client unterstützt Navigation in großen Mengen.
3. Schritt 3: Medien-URL und passende Variante bestimmen. Prüfpunkt: Asset wird in geeigneter Größe geladen.
4. Schritt 4: Fehlende Assets und Zugriffsfehler behandeln. Prüfpunkt: Oberfläche bleibt stabil.
5. Schritt 5: Cache- und CDN-Verhalten prüfen. Prüfpunkt: Ressourcen werden effizient ausgeliefert.

6. Sicherheit, Caching und Fehlerverträge

Öffentliche und geschützte Zugriffe werden getrennt, während Fehler und Aktualität konsistent behandelt werden. Zu jedem Arbeitsschritt wird geprüft, ob Konfiguration, Inhalt und Betriebszustand dem erwarteten Ergebnis entsprechen.

Schritt-für-Schritt

1. Schritt 1: Öffentliche, Preview- und geschützte Endpunkte klassifizieren. Prüfpunkt: Zugriffsmodell ist klar.
2. Schritt 2: Token oder Sitzungsdaten nur in geeigneter Laufzeit verwenden. Prüfpunkt: Secrets gelangen nicht in öffentliche Clients.
3. Schritt 3: Cache-Control, ETag oder anwendungsspezifische Caches planen. Prüfpunkt: Aktualität und Last sind ausbalanciert.
4. Schritt 4: Standardisiertes Fehlerobjekt im Client abbilden. Prüfpunkt: Fehlerbehandlung ist einheitlich.
5. Schritt 5: Sicherheits- und Cache-Negativtests durchführen. Prüfpunkt: Datenleck und veraltete Ausgabe werden verhindert.

7. Contract Tests und API-Betrieb

API-Verträge werden automatisiert geprüft und ihre Qualität im Betrieb überwacht. Zu jedem Arbeitsschritt wird geprüft, ob Konfiguration, Inhalt und Betriebszustand dem erwarteten Ergebnis entsprechen.

Schritt-für-Schritt

1. Schritt 1: Schema- und Fixture-Tests für Kernantworten anlegen. Prüfpunkt: Inkompatible Änderungen werden erkannt.
2. Schritt 2: Integrationstest gegen eine kontrollierte Umgebung ausführen. Prüfpunkt: Vertrag und Plattform stimmen überein.
3. Schritt 3: Latenz, Fehlerquote und Antwortgröße messen. Prüfpunkt: Betriebsqualität ist sichtbar.
4. Schritt 4: Breaking Change simulieren und Clientverhalten prüfen. Prüfpunkt: Fehler wird früh und verständlich gemeldet.
5. Schritt 5: Release- und Rückfallregel dokumentieren. Prüfpunkt: API-Änderungen sind beherrschbar.

Praxisprojekt und Qualitätssicherung

Ein API-Client lädt Seiten, Komponenten, Beziehungen, Suchergebnisse und Medien, stellt sie typisiert bereit, behandelt Fehler und Cache und wird mit Contract- sowie Integrationstests abgesichert. Die Übung wird mit einer Abnahmeliste abgeschlossen, die Funktionsprüfung, Fehlerfall, Dokumentation und reproduzierbaren Wiederanlauf umfasst.

Zielgruppe und Voraussetzungen

Zielgruppe: Frontend-, Backend- und Full-Stack-Entwicklung, Integrationsentwicklung, Lösungsarchitektur und technische Qualitätssicherung.

Voraussetzungen: Sichere Kenntnisse in HTTP, JSON, JavaScript oder TypeScript und Git; Grundkenntnisse in CrafterCMS Content-Modellen.

Didaktik und Arbeitsweise

Kurze Fachimpulse wechseln mit Demonstrationen, geführten Konfigurationsschritten, eigenständigen Übungen, negativen Testfällen und strukturierten Auswertungen. Ergebnisse werden in Checklisten, Mappingtabellen, Testfällen oder Runbooks festgehalten, damit die erarbeiteten Verfahren im Projekt- und Betriebsalltag wiederholbar bleiben.