Seminar Squidex – API-Entwicklung mit REST, GraphQL und Abfragen

Squidex stellt Inhalte API-first bereit. Produktive Clients benötigen jedoch mehr als einzelne erfolgreiche Requests: Datenverträge, Authentifizierung, Abfragestrategien, Referenzauflösung, Pagination, Fehlerbehandlung und Beobachtbarkeit müssen gemeinsam entworfen werden.

Das Seminar entwickelt schrittweise einen robusten Content-Client. REST, GraphQL, Volltextsuche sowie strukturierte Filter- und Sortierabfragen werden anhand derselben Domäne verglichen und mit automatisierten Tests abgesichert.

Zielgruppe

Backend- und Frontend-Entwickler, Integrationsarchitekten, technische Projektleiter und Teams für Headless-Anwendungen

Voraussetzungen

Sichere Kenntnisse in HTTP, JSON und einer Programmiersprache; Grundkenntnisse zu Authentifizierung und asynchroner Programmierung

Seminarziele

• API-Zugänge, Endpunkte und Datenverträge sicher einrichten.
• REST- und GraphQL-Abfragen passend zum Nutzungsszenario auswählen.
• Filterung, Sortierung, Volltextsuche und Pagination korrekt kombinieren.
• Referenzen, Lokalisierungen und Assets effizient auflösen.
• Resiliente Clients mit Caching, Fehlerbehandlung, Telemetrie und Tests entwickeln.

Inhaltsübersicht

1. Zielgruppe und Voraussetzungen
2. Seminarziele
3. API-Landschaft und Zugriffskonzept
4. REST-Endpunkte und Datenverträge
5. Filter, Sortierung, Suche und Pagination
6. GraphQL für präzise Ausgaben
7. Assets, Referenzen und Lokalisierungen
8. Resilienz, Caching und automatisierte API-Tests
9. Praxisprojekt und Abnahme

1. API-Landschaft und Zugriffskonzept

Dieser Themenblock verbindet fachliche Entscheidung, konkrete Konfiguration und überprüfbare Abnahme. Die Schritte werden an einer durchgängigen Beispiel-App umgesetzt und mit geeigneten Positiv- und Negativfällen kontrolliert.

Schrittweises Vorgehen

1. App, Schema, Content API und Management API fachlich einordnen.
2. Technischen Client mit minimalen Rechten und getrenntem Secret anlegen.
3. Tokenbeschaffung und sichere Konfigurationsübergabe implementieren.
4. Ersten lesenden Request reproduzierbar ausführen und protokollieren.
5. Fehlende, abgelaufene und unzureichende Berechtigungen gezielt testen.

Prüfpunkte

• Die Konfiguration erfüllt den beschriebenen fachlichen Zweck ohne unnötige Sonderfälle.
• Berechtigungen, Fehlerzustände und Auswirkungen auf abhängige Komponenten sind geprüft.
• Ergebnis, offene Punkte und Wiederholungsweg sind nachvollziehbar dokumentiert.

2. REST-Endpunkte und Datenverträge

Der Abschnitt wird als vollständiger Arbeitsablauf bearbeitet: Ausgangslage erfassen, Zielzustand festlegen, Konfiguration umsetzen, Verhalten testen und die betriebliche beziehungsweise redaktionelle Übergabe dokumentieren.

Schrittweises Vorgehen

1. Schema- und Content-Endpunkte anhand eines fachlichen Use Cases auswählen.
2. Antwortmodelle typisieren und optionale beziehungsweise lokalisierte Felder abbilden.
3. Create-, Read-, Update- und Publish-Abläufe mit Statusprüfung implementieren.
4. ETags und konkurrierende Änderungen in die Schreiblogik einbeziehen.
5. Fehlerantworten in ein konsistentes Client-Fehlermodell übersetzen.

Prüfpunkte

• Die Konfiguration erfüllt den beschriebenen fachlichen Zweck ohne unnötige Sonderfälle.
• Berechtigungen, Fehlerzustände und Auswirkungen auf abhängige Komponenten sind geprüft.
• Ergebnis, offene Punkte und Wiederholungsweg sind nachvollziehbar dokumentiert.

3. Filter, Sortierung, Suche und Pagination

Die Inhalte werden nicht isoliert demonstriert. Jede Entscheidung wird anhand von Auswirkungen auf Redaktion, API, Sicherheit, Betrieb und spätere Änderungen bewertet und anschließend praktisch validiert.

Schrittweises Vorgehen

1. Abfrageanforderungen in Filter-, Sortier- und Suchkriterien zerlegen.
2. Strukturierte Filter gegen Feldtypen und Indexierbarkeit prüfen.
3. Volltextsuche mit fachlichen Einschränkungen kombinieren.
4. Seitengröße, Offset beziehungsweise Fortsetzung und Gesamtmenge behandeln.
5. Grenzfälle mit leeren Ergebnissen, großen Mengen und ungültigen Filtern testen.

Prüfpunkte

• Die Konfiguration erfüllt den beschriebenen fachlichen Zweck ohne unnötige Sonderfälle.
• Berechtigungen, Fehlerzustände und Auswirkungen auf abhängige Komponenten sind geprüft.
• Ergebnis, offene Punkte und Wiederholungsweg sind nachvollziehbar dokumentiert.

4. GraphQL für präzise Ausgaben

Im Mittelpunkt steht ein reproduzierbares Vorgehen. Konfiguration, Testdaten, Prüfschritte und Abnahmekriterien werden so festgehalten, dass der Ablauf in einer eigenen Umgebung wiederholt werden kann.

Schrittweises Vorgehen

1. GraphQL-Schema und verfügbare Typen aus dem Content-Modell ableiten.
2. Abfragen mit genau den benötigten Feldern und Lokalisierungen formulieren.
3. Referenzfelder und verschachtelte Strukturen kontrolliert auflösen.
4. Variablen, Fragmente und wiederverwendbare Query-Bausteine einsetzen.
5. Antwortgröße und Laufzeit mit alternativen REST-Abfragen vergleichen.

Prüfpunkte

• Die Konfiguration erfüllt den beschriebenen fachlichen Zweck ohne unnötige Sonderfälle.
• Berechtigungen, Fehlerzustände und Auswirkungen auf abhängige Komponenten sind geprüft.
• Ergebnis, offene Punkte und Wiederholungsweg sind nachvollziehbar dokumentiert.

5. Assets, Referenzen und Lokalisierungen

Dieser Themenblock verbindet fachliche Entscheidung, konkrete Konfiguration und überprüfbare Abnahme. Die Schritte werden an einer durchgängigen Beispiel-App umgesetzt und mit geeigneten Positiv- und Negativfällen kontrolliert.

Schrittweises Vorgehen

1. Content-Referenzen gegen fehlende oder unveröffentlichte Ziele absichern.
2. Asset-Metadaten, Varianten und geschützte Auslieferung in das Clientmodell integrieren.
3. Sprachauflösung und Fallback-Regeln explizit konfigurieren.
4. Zirkuläre und tiefe Referenzketten durch feste Auflösungsgrenzen beherrschen.
5. Konsistenztests für verknüpfte Inhalte und Medien automatisieren.

Prüfpunkte

• Die Konfiguration erfüllt den beschriebenen fachlichen Zweck ohne unnötige Sonderfälle.
• Berechtigungen, Fehlerzustände und Auswirkungen auf abhängige Komponenten sind geprüft.
• Ergebnis, offene Punkte und Wiederholungsweg sind nachvollziehbar dokumentiert.

6. Resilienz, Caching und automatisierte API-Tests

Der Abschnitt wird als vollständiger Arbeitsablauf bearbeitet: Ausgangslage erfassen, Zielzustand festlegen, Konfiguration umsetzen, Verhalten testen und die betriebliche beziehungsweise redaktionelle Übergabe dokumentieren.

Schrittweises Vorgehen

1. Timeouts, Wiederholungen und Circuit-Breaker nur für geeignete Fehlerklassen definieren.
2. Cache-Schlüssel aus App, Schema, Sprache, Query und Berechtigungskontext bilden.
3. Rate- und Lastgrenzen durch kontrollierte Parallelität berücksichtigen.
4. Contract-, Integrations- und Negativtests für zentrale Abfragen erstellen.
5. Korrelation, Metriken und strukturierte Logs für den Produktionsbetrieb ergänzen.

Prüfpunkte

• Die Konfiguration erfüllt den beschriebenen fachlichen Zweck ohne unnötige Sonderfälle.
• Berechtigungen, Fehlerzustände und Auswirkungen auf abhängige Komponenten sind geprüft.
• Ergebnis, offene Punkte und Wiederholungsweg sind nachvollziehbar dokumentiert.

Praxisprojekt und Abnahme

Ein typisierter Content-Client liefert lokalisierte Inhalte, löst Referenzen und Assets auf und bleibt bei Fehlern und großen Datenmengen kontrollierbar.

Arbeitsschritte

1. Fachliche Lese- und Schreibfälle als API-Verträge festlegen.
2. Authentifizierung, REST-Basisclient und Fehlerabbildung implementieren.
3. Suche, Filterung, Pagination und GraphQL-Abfragen ergänzen.
4. Caching, Referenzauflösung und Telemetrie integrieren.
5. Contract- und Lasttests ausführen und die Clientstrategie dokumentieren.

Abnahmekriterien

• Der fachliche Anwendungsfall ist mit repräsentativen Daten vollständig durchgespielt.
• Fehler-, Berechtigungs- und Wiederanlaufszenarien sind kontrolliert geprüft.
• Konfiguration, Tests und Verantwortlichkeiten sind so dokumentiert, dass der Transfer in eine eigene Umgebung möglich ist.