REST APIs mit Quarkus entwickeln

REST APIs mit Quarkus entwickeln

0:00 Die REST-Schicht ist der Teil einer Migration, bei dem man am schnellsten sichtbare Erfolge hat — und derjenige, der am wenigsten verzeiht. Denn hier hängen fremde Clients dran, die von Ihrem Umbau nichts wissen und auch nichts wissen sollen. Für sie darf sich nichts ändern: nicht die Pfade, nicht die Statuscodes, nicht die Antwortformate und vor allem nicht das Fehlerformat.

0:21 In diesem Modul sehen wir uns beide Wege an — die Kompatibilitätsvariante mit Spring-Annotationen und den direkten Weg über Jakarta REST.

REST APIs mit Quarkus entwickeln

0:29 Zweiter der drei täglichen Bausteine. Wir schauen auf die Annotationen und ihre Grenzen, dann auf Serialisierung, Validierung und Fehlerbehandlung — den Teil, der Verträge bricht, wenn man nicht hinsieht. Zum Schluss geht es um ausgehende Aufrufe und um OpenAPI als Werkzeug, mit dem sich ein Vertrag überhaupt vergleichen lässt.

Spring MVC und Quarkus REST gegenübergestellt

0:49 Beginnen wir mit den Annotationen. Zwei Schreibweisen, dasselbe Ergebnis — und eine Empfehlung, die Quarkus recht deutlich ausspricht. Quarkus REST ist die Jakarta-REST-Implementierung von Quarkus, von Grund auf neu geschrieben und auf der Vert.x-Schicht aufgesetzt. Sie ist der Nachfolger dessen, was früher RESTEasy Reactive hieß — falls Ihnen dieser Name in älteren Beispielen begegnet.

1:13 Wer Spring-Annotationen behalten möchte, ergänzt die Spring-Web-Extension. Wichtig: Für JSON braucht es zusätzlich eine Jackson-Extension; die Spring-Web-Kompatibilität allein genügt nicht. Das ist eine der häufigsten Startschwierigkeiten und in zwei Minuten behoben, wenn man es weiß. Die Tabelle ist kein Wörterbuch zum Auswendiglernen, sondern zeigt ein Prinzip: Jakarta REST trennt Pfad und Methode, Spring bündelt beides in einer Annotation.

1:40 Praktisch heißt das, aus einem Mapping werden zwei Angaben. Interessant sind die Parameter: Es gibt jeweils eine standardkonforme Variante und eine kürzere Quarkus-Schreibweise — beide funktionieren, entscheiden Sie sich im Team für eine. Und die Fußnote zeigt, dass die Kompatibilität weiter reicht, als man denkt: Auch Cookie-Werte, Matrix-Variablen und die zentrale Fehlerbehandlung sind abgedeckt.

2:04 Oben die Spring-Variante, unten Jakarta REST — derselbe Endpunkt, dieselbe URL, dieselbe Antwort. Was Sie hier sehen, ist der beruhigende Teil: Der Umbau ist mechanisch und in wenigen Minuten erledigt. Was Sie nicht sehen, steht in der Fußnote und ist der eigentliche Punkt: Der Spring Application Context wird nicht gestartet.

2:24 Die Annotationen oben sind Etiketten, die Quarkus liest — mehr nicht. Alles, was in Spring hinter diesen Annotationen an Infrastruktur hängt, ist hier nicht vorhanden. Vier Grenzen, die man vor dem Umbau kennen sollte. Die zentrale Fehlerbehandlung funktioniert nur in einer eigenen Advice-Klasse, nicht pro Controller — und von dieser Klasse ist auch nur der Exception-Handler-Teil abgedeckt.

2:48 Der Zugriff auf die Servlet-API gibt es nur mit der klassischen Variante, nicht mit dem neuen Stack; das ist eine Entscheidung, die Sie früh treffen müssen. Und die Rückgabetypen sind begrenzt auf Primitive, Strings, POJOs und das Response-Objekt. Wer im Bestand exotischere Rückgabetypen hat, sollte genau hier nachsehen, bevor er plant.

Serialisierung, Validierung und Fehlerbehandlung

3:08 Jetzt zu dem Teil, in dem Verträge brechen, ohne dass es jemand merkt. Denn zum API-Vertrag gehört nicht nur die erfolgreiche Antwort, sondern genauso die Antwort im Fehlerfall. Zwei Extensions teilen sich die Arbeit: Jackson serialisiert, Hibernate Validator prüft. Interessant ist das Zusammenspiel: Ein Parameter, den Sie am Endpunkt als zu validieren markieren, wird automatisch geprüft, und bei einem Verstoß antwortet Quarkus mit Statuscode 400 und einem strukturierten Bericht aus Titel, Status und einer Liste der Verstöße.

3:40 Das ist komfortabel — und genau deshalb gefährlich. Denn dieses Format ist mit hoher Wahrscheinlichkeit nicht das, was Ihre bisherige Anwendung geliefert hat. Oben zwei Zeilen, unten das, was dabei herauskommt. Der Code ist unspektakulär, die Antwort darunter ist der eigentliche Inhalt dieser Folie: Merken Sie sich die Struktur mit Titel, Status und Verstoßliste, und vergleichen Sie sie mit dem, was Ihre Clients heute bekommen.

4:05 Und beachten Sie die Fußnote: Wenn die Prüfung nicht am Endpunkt, sondern tiefer in einem Service stattfindet, bekommen Sie keine schöne 400er-Antwort, sondern eine Ausnahme, die jemand behandeln muss. Wo die Validierung sitzt, ist also eine Architekturentscheidung, keine Geschmacksfrage. Die Antwort lautet: an genau einer Stelle, und zwar bewusst gewählt.

4:25 Ein eigener Exception Mapper bestimmt das Antwortformat vollständig und löst damit auch den eingebauten Mapper der Validierung ab. Filter setzen Querschnittliches vor und nach dem Aufruf. Und wer an der Serialisierung schrauben muss, hat mit Jackson die gewohnten Mittel. Wichtig ist die Reihenfolge im Projekt: Legen Sie das Fehlerformat fest, bevor Sie Endpunkte umziehen.

4:47 Sonst übernehmen Sie unbemerkt das Standardformat des Frameworks — und ändern damit einen Vertrag, über den nie jemand gesprochen hat. Der erste Punkt ist der teuerste der ganzen REST-Migration: Das Fehlerformat ändert sich, und die Clients merken es erst in Produktion. Der zweite ist eine Nachlässigkeit mit Folgen: Die Validierungsmarkierung fehlt am Endpunkt, und die Prüfung greift erst tief im Service.

5:11 Der dritte ist subtil: Das eigene Fehlerformat wird gebaut, aber der eingebaute Mapper bleibt aktiv und gewinnt. Und der vierte trifft fast jedes Projekt: Zeitstempel und Zahlen werden anders serialisiert als zuvor — ein Sekundenbruchteil mehr Genauigkeit reicht, um einen fremden Parser zu irritieren.

Clients, Dokumentation und API-Stabilität

5:29 Bisher ging es um eingehende Aufrufe. Sehen wir uns an, wie Quarkus ausgehende Aufrufe behandelt — und wie Sie überhaupt nachweisen, dass Ihr Vertrag stabil geblieben ist. Der REST Client dreht die gewohnte Richtung um: Statt einen Aufruf zu programmieren, beschreiben Sie ihn als Interface mit denselben Annotationen, die Sie für Endpunkte benutzen.

5:50 Eine Annotation macht daraus einen Client, eine zweite injiziert ihn. Das Bild: Sie schreiben keine Bestellprozedur, Sie hängen eine Speisekarte an die Wand. Die Zieladresse steht in der Konfiguration, nicht im Code — und damit lässt sie sich je Umgebung ändern, ohne dass jemand etwas neu übersetzen muss. Vier Zeilen, und der ausgehende Aufruf ist beschrieben.

6:11 Wichtig ist der Konfigurationsschlüssel, den Sie hier mitgeben: Über ihn hängen später URL und Zeitgrenzen in der Konfiguration. Genau das sollten Sie sich angewöhnen — jeder Client bekommt einen sprechenden Schlüssel, sonst stehen später Klassennamen in Ihrer Konfigurationsdatei. Und noch ein Hinweis für später: Auf dieses Interface setzen wir in Modul dreizehn die Fehlertoleranz.

6:34 Timeout, Wiederholung und Circuit Breaker sind Annotationen, die genau hier andocken. OpenAPI ist in dieser Migration mehr als Dokumentation — es ist ein Messinstrument. Die Extension erzeugt das Schema unter einem festen Pfad, Sie können es beim Build sogar als Datei ablegen lassen. Und damit haben Sie etwas, das sich maschinell vergleichen lässt: Schema vorher, Schema nachher. Ein Unterschied im Diff ist ein Unterschied für Ihre Clients.

7:01 Eine Sache müssen Sie wissen: Die Swagger-Oberfläche ist nur in den Entwicklungs- und Testprofilen aktiv. Das ist kein Fehler, sondern eine bewusste Voreinstellung — und meistens die richtige. Der erste Punkt ist eine typische Supportanfrage: Die Swagger-Oberfläche fehlt in Produktion. Sie ist dort absichtlich abgeschaltet.

7:21 Der zweite ist die vertane Chance: Das Schema wird erzeugt, aber nie mit dem alten verglichen — dabei ist genau das der billigste Test, den Sie in dieser Migration bekommen können. Drittens werden Rückgabetypen reaktiv gemacht, obwohl der Aufrufer blockierend bleibt; das bringt nichts und kostet Lesbarkeit. Und viertens bleiben Timeouts auf den Vorgabewerten — was so lange gutgeht, bis der erste fremde Dienst langsam wird.

Übung

7:46 In der Übung machen Sie beides: erst die bequeme Variante, dann die saubere — und prüfen anschließend, ob wirklich dasselbe herauskommt. Sie überführen die Endpunkte für Becherausgabe und Rücknahme zweimal: einmal mit der Spring-Web-Kompatibilität, einmal mit Jakarta REST. Erfolgreich sind Sie nicht, wenn beide Varianten laufen — sondern wenn beide für dieselben Anfragen identische Statuscodes und Antwortkörper liefern und das erzeugte OpenAPI-Schema keinen Unterschied zeigt.

8:14 Und der Hinweis auf der Folie ist ernst gemeint: Prüfen Sie den Fehlerfall ausdrücklich mit. Dort weichen Migrationen am häufigsten ab, und dort schaut am seltensten jemand hin. Der zweite Schritt ist der Trick dieser Übung: Halten Sie das OpenAPI-Schema als Vergleichsstand fest, solange noch alles beim Alten ist. Danach können Sie jeden weiteren Schritt gegen diesen Stand prüfen.

8:37 Das ist deutlich schneller als manuelles Vergleichen und findet Dinge, die man beim Lesen übersieht — einen geänderten Typ, ein fehlendes Feld, einen anderen Statuscode. Die Fußnote schränkt zurecht ein: Ein Schemavergleich ersetzt keinen Contract Test. Aber er findet die groben Brüche in Sekunden. Achten Sie besonders auf den ersten Punkt: Wer nur den Erfolgsfall vergleicht, hat die halbe Schnittstelle geprüft.

9:02 Zweitens ist die Versuchung groß, die Kompatibilitätsvariante zu überspringen, weil man ja weiß, wo man hinwill — dann treten aber alle Fehler gleichzeitig auf, und die Zuordnung wird mühsam. Drittens verschiebt sich gern ein Pfad um einen Schrägstrich; das fällt beim Lesen nicht auf, im Schemavergleich sofort. Und viertens: Wenn keine Spring-Annotation mehr im Code steht, gehört die Extension aus dem Build heraus.