Seminar Flask API-Entwicklung mit REST, JSON und OpenAPI

Stabile APIs entstehen nicht durch das bloße Zurückgeben von JSON. Erforderlich sind ein belastbares Ressourcenmodell, eindeutige HTTP-Semantik, konsequente Eingabeprüfung, ein einheitliches Fehlerformat und überprüfbare Verträge.

Das Seminar führt von der fachlichen Modellierung über die Implementierung in Flask bis zur maschinenlesbaren OpenAPI-Beschreibung. Authentifizierung, Missbrauchsschutz, Versionierung und automatisierte Vertragstests werden von Beginn an mitgeführt.

Inhaltsübersicht

1. HTTP, WSGI und Flask-Lebenszyklus
2. Ressourcenmodell und HTTP-Semantik
3. JSON-Validierung und Serialisierung
4. Fehlerformat, Versionierung und Kompatibilität
5. OpenAPI-Beschreibung und Schnittstellendokumentation
6. API-Authentifizierung, Autorisierung und Missbrauchsschutz
7. Service-, Repository- und Domänenschichten
8. API-, Vertrags- und Integrationstests
9. Strukturiertes Logging und Korrelationskennungen
10. Praxisprojekt und Wissenssicherung

Lernziele

• Ressourcen und Operationen in konsistente HTTP-Verträge überführen.
• JSON-Eingaben und -Ausgaben mit expliziten Schemas absichern.
• Einheitliche Fehlerobjekte und eine tragfähige Versionierungsstrategie entwickeln.
• OpenAPI-Beschreibungen mit der Implementierung synchron halten.
• Zugriffsschutz, Ratenbegrenzung und Vertragstests integrieren.

Zielgruppe

Backend-Entwickler, Integrationsentwickler, Softwarearchitekten und Teams, die interne oder öffentliche HTTP-Schnittstellen mit Flask entwickeln und pflegen.

Voraussetzungen

Gute Python-Kenntnisse, sichere Grundlagen in Flask sowie ein grundlegendes Verständnis von HTTP. Datenbankkenntnisse sind für die Übungen hilfreich.

Seminarinhalte

1. HTTP, WSGI und Flask-Lebenszyklus

Das Zusammenspiel von Browser, Reverse Proxy, WSGI-Server und Anwendung wird technisch eingeordnet.

1. Schritt 1: HTTP-Anfrage, Statuscode, Header und Nachrichtentext anhand einer vollständigen Transaktion zerlegen.
2. Schritt 2: WSGI-Anwendung und Serverrolle unterscheiden und die Grenzen des integrierten Entwicklungsservers festhalten.
3. Schritt 3: Anwendungs-, Request- und Response-Lebenszyklus mit Hooks und Kontextobjekten nachvollziehen.
4. Schritt 4: Eine Anfrage vom Eingang bis zur Antwort protokollieren und Fehlerstellen den zuständigen Schichten zuordnen.

2. Ressourcenmodell und HTTP-Semantik

API-Endpunkte werden aus fachlichen Ressourcen und stabilen HTTP-Kontrakten abgeleitet.

1. Schritt 1: Ressourcen, Identitäten und Beziehungen aus Anwendungsfällen bestimmen.
2. Schritt 2: Methoden, Statuscodes und Idempotenz pro Operation festlegen.
3. Schritt 3: Filter, Sortierung, Pagination und Feldselektion konsistent definieren.
4. Schritt 4: Beispielrequests und -responses als überprüfbare Verträge formulieren.

3. JSON-Validierung und Serialisierung

Eingaben und Ausgaben werden über explizite Schemas kontrolliert, damit interne Modelle nicht ungefiltert nach außen gelangen.

1. Schritt 1: Content-Type und JSON-Struktur vor fachlicher Verarbeitung prüfen.
2. Schritt 2: Pflichtfelder, Typen, Formate und verschachtelte Objekte in Schemas festlegen.
3. Schritt 3: Eingabe-, Domänen- und Ausgabemodelle voneinander trennen.
4. Schritt 4: Unbekannte Felder, Nullwerte und Versionsunterschiede automatisiert testen.

4. Fehlerformat, Versionierung und Kompatibilität

Fehlerantworten und Änderungsregeln werden als Teil des öffentlichen API-Vertrags behandelt.

1. Schritt 1: Einheitliches Fehlerobjekt mit Code, Meldung, Details und Korrelationskennung definieren.
2. Schritt 2: Validierungs-, Authentifizierungs-, Konflikt- und Serverfehler eindeutig abbilden.
3. Schritt 3: Versionierungsstrategie für Pfad, Header oder Medienformat anhand der Produktanforderungen wählen.
4. Schritt 4: Abwärtskompatibilität und Deprecation-Verhalten mit Vertragstests absichern.

5. OpenAPI-Beschreibung und Schnittstellendokumentation

Die maschinenlesbare Beschreibung wird aus realen Verträgen aufgebaut und gegen die Implementierung geprüft.

1. Schritt 1: Operationen, Parameter, Schemas und Antwortvarianten vollständig modellieren.
2. Schritt 2: Sicherheitsverfahren, Beispiele und Fehlerobjekte in der Spezifikation ergänzen.
3. Schritt 3: Dokumentation aus der Spezifikation bereitstellen, ohne interne Verwaltungsendpunkte offenzulegen.
4. Schritt 4: Spezifikation linten und Abweichungen zur Laufzeit in der CI erkennen.

6. API-Authentifizierung, Autorisierung und Missbrauchsschutz

Zugriffsschutz wird pro Ressource und Operation durchgesetzt und gegen automatisierten Missbrauch ergänzt.

1. Schritt 1: Sitzungs-, Token- und föderierte Verfahren nach Clienttyp auswählen.
2. Schritt 2: Berechtigungen in Services prüfen und nicht allein auf ausgeblendete Routen vertrauen.
3. Schritt 3: Ratenbegrenzung, Größenlimits und Schutz vor wiederholten Fehlversuchen planen.
4. Schritt 4: Fehlende, abgelaufene und manipulierte Zugangsdaten mit Negativtests prüfen.

7. Service-, Repository- und Domänenschichten

Geschäftslogik wird von HTTP und Persistenz getrennt, damit sie unabhängig testbar und wiederverwendbar bleibt.

1. Schritt 1: View-Funktionen auf Eingabe, Serviceaufruf und Response-Abbildung reduzieren.
2. Schritt 2: Services für Anwendungsfälle und Repositories für Datenzugriffe definieren.
3. Schritt 3: Domänenfehler statt HTTP-Ausnahmen aus tieferen Schichten zurückgeben.
4. Schritt 4: Servicefälle mit Fakes testen und Integrationspfade separat absichern.

8. API-, Vertrags- und Integrationstests

Schnittstellen werden gegen Statuscodes, Schemas, Nebenwirkungen und Kompatibilitätsregeln getestet.

1. Schritt 1: Test-Client mit wiederverwendbaren Authentifizierungs- und Daten-Fixtures konfigurieren.
2. Schritt 2: Erfolgs-, Validierungs-, Konflikt- und Berechtigungsfälle tabellarisch abdecken.
3. Schritt 3: Response-Schemas und OpenAPI-Beispiele automatisiert vergleichen.
4. Schritt 4: Datenbank-, Queue- und Fremdsystemintegrationen in getrennten Teststufen prüfen.

9. Strukturiertes Logging und Korrelationskennungen

Protokolle werden so gestaltet, dass technische Abläufe und einzelne Requests zuverlässig nachvollziehbar bleiben.

1. Schritt 1: Logger-Hierarchie, Level und Handler zentral konfigurieren.
2. Schritt 2: Request-, Benutzer- und Korrelationskennung als strukturierte Felder ergänzen.
3. Schritt 3: Sensible Daten, Tokens und vollständige Request-Körper konsequent filtern.
4. Schritt 4: Logausgabe für Entwicklung und zentrale Sammlung getrennt testen.

Praxisprojekt

Eine mehrteilige Ressourcen-API wird aus Anwendungsfällen abgeleitet, implementiert, dokumentiert und getestet. Enthalten sind CRUD-Operationen, Filterung, Pagination, Validierungsfehler, Zugriffsregeln und eine OpenAPI-Spezifikation.

Methodik

Kurze fachliche Einordnungen wechseln mit Demonstrationen, geführten Umsetzungen, Fehleranalysen und eigenständigen Übungen. Jede größere Änderung wird durch einen Test, eine Diagnose oder eine betriebliche Prüfroutine abgesichert. Die Arbeitsstände werden schrittweise zu einem durchgängigen Beispielprojekt zusammengeführt.