REST

REST

0:00 REST ist das Rückgrat fast jeder modernen Anwendung. Jedes Mal, wenn eine App auf dem Handy Daten nachlädt oder zwei Dienste in der Cloud miteinander reden, steckt im Kern eine solche Schnittstelle. Das Prinzip ist bewusst einfach: Adressen für Dinge, dazu die vertrauten HTTP-Verben zum Lesen, Anlegen, Ändern und Löschen.

0:18 In diesem Modul schauen wir, wie Quarkus das umsetzt — nicht mit einer Eigenentwicklung, sondern auf einem etablierten Standard. Unsere Werkbank-Daten aus dem letzten Modul bekommen also eine Tür nach außen. Behalten Sie im Kopf: Wir bauen hier keine Raketenwissenschaft, sondern eine saubere Schnittstelle, an der sich alle wichtigen Muster zeigen lassen.

Jakarta REST in Quarkus

0:39 Bevor wir Code schreiben, klären wir das Fundament. Womit genau setzt Quarkus REST um — und warum ist das eine gute Nachricht für alle, die schon einmal mit Java-Enterprise gearbeitet haben? Die kurze Antwort lautet: Sie müssen kaum etwas Neues lernen. Die längere hat mit einer Umbenennung zu tun, die viele Suchergebnisse im Netz bis heute verwirrt, und mit einer Erweiterung, die zwei sehr unterschiedliche Programmiermodelle unter einem Dach vereint.

1:05 Stellen Sie sich einen genormten Steckadapter vor: Jakarta REST ist der Java-Standard dafür, wie man Endpunkte beschreibt — herstellerunabhängig, seit Jahren etabliert. Wenn Ihnen dieser Name nichts sagt, kennen Sie ihn vermutlich unter dem alten Kürzel JAX-RS; umbenannt wurde er beim Wechsel zur Eclipse Foundation, geblieben ist alles.

1:25 Quarkus erfindet hier nichts Neues, sondern spricht diese vertraute Sprache in einer Implementierung namens Quarkus REST. Sie annotieren eine Methode als GET oder POST, und das Framework kümmert sich um den Rest. Der Gewinn ist Übertragbarkeit: Was Sie hier lernen, gilt auch dann, wenn Sie das Framework wechseln. Der interessanteste Punkt ist der erste: Ein und dieselbe Erweiterung trägt den klassischen, blockierenden Stil genauso wie den reaktiven.

1:52 Sie müssen sich also nicht am Anfang eines Projekts festlegen und können später umsteigen, ohne die Grundlage zu wechseln — wir nutzen das in Modul fünf aus. Ansonsten bekommen Sie, was man erwartet: alle HTTP-Verben, eigene dazu, wenn Sie sie brauchen. Angenehm ist, wie die Anfrage bei Ihnen ankommt. Pfadteile, Query-Parameter, Header, Cookies — all das landet als normaler Methodenparameter. Kein Auslesen, kein Umwandeln, kein Prüfen auf null.

2:19 Diese Handgriffe hat man früher tausendfach geschrieben. Zwei Punkte, die Zeit kosten können. Der erste ist historisch: Ältere Anleitungen — und davon gibt es viele — nennen eine Erweiterung mit "resteasy-reactive" im Namen. Die gibt es so nicht mehr, sie heißt heute schlicht Quarkus REST. Wenn Sie in einem Tutorial über den alten Namen stolpern, ist der Inhalt meist noch richtig, nur die Abhängigkeit veraltet.

2:45 Der zweite Punkt betrifft den Anfragekörper: Der wird nicht annotiert. Was übrig bleibt, wenn alle anderen Parameter zugeordnet sind, ist der Body — und Jackson macht daraus ein Objekt. Und eine kleine Erleichterung zum Schluss: Heißt Ihr Parameter genauso wie die Pfadvariable, dürfen Sie die Annotation weglassen. Diese Tabelle muss man nicht lernen, sondern verstehen — dann ergibt sie sich von selbst.

3:10 Das Prinzip lautet: Jeder Teil einer HTTP-Anfrage hat seine eigene Annotation, und alle folgen demselben Namensmuster. Was im Pfad steht, was hinter dem Fragezeichen kommt, was im Header oder im Cookie steckt, was aus einem Formular stammt — für jedes gibt es eine Entsprechung, und alle heißen gleich aufgebaut. Wenn Sie eine davon kennen, kennen Sie alle. Der einzige Sonderfall ist der Anfragekörper, und der ist deshalb besonders, weil er gar keine Annotation hat.

3:38 Diese Konsistenz ist der eigentliche Komfort: Man muss nicht nachschlagen, man rät richtig.

REST umsetzen

3:44 Genug Überblick. Bauen wir eine echte Ressource — mit allen Operationen, die eine Anwendung braucht: lesen, anlegen, ändern, löschen. Wir nehmen dafür die Kunden aus unserer Werkbank und gehen sie Schritt für Schritt durch. Achten Sie dabei weniger auf die Syntax als auf die Entscheidungen, die nebenbei getroffen werden: Welchen Statuscode liefert man wann, wohin gehört die Transaktionsgrenze, und was passiert eigentlich, wenn der gesuchte Datensatz gar nicht existiert?

4:11 Der Ablauf ist in jedem Projekt derselbe, deshalb lohnt es sich, ihn einmal bewusst durchzugehen. Zwei Erweiterungen — eine für REST, eine für die JSON-Verarbeitung. Dann eine Klasse mit ihrer Adresse, ein Vermerk, dass hier JSON hinein- und hinausgeht, und die Datenzugriffsklasse aus dem letzten Modul über den Konstruktor hinein.

4:30 Danach kommen die Methoden. Achten Sie auf den vierten Schritt: Wir injizieren wieder über den Konstruktor, aus demselben Grund wie in Modul eins. Ein Endpunkt, den man im Test nicht mit einem Ersatz-Repository füttern kann, ist ein Endpunkt, den man nur noch mit laufender Datenbank prüfen kann. Hier steckt eine Design-Entscheidung, die man leicht übersieht.

4:51 Es gibt zwei Wege, eine Suche anzubieten: eine eigene Adresse dafür, oder ein optionaler Parameter an der bestehenden. Wir nehmen den zweiten — dieselbe Adresse liefert alles, wenn nichts angegeben ist, und filtert, wenn doch. Das hält die Schnittstelle klein und entspricht dem, was Nutzer erwarten. Worauf es beim Code ankommt: Der Rückgabetyp bleibt in beiden Fällen eine Liste.

5:14 Auch wenn nur ein Treffer herauskommt. Eine Schnittstelle, die mal ein Objekt und mal eine Liste liefert, zwingt jeden Aufrufer zu einer Fallunterscheidung — das ist unhöflich. Zwei Kleinigkeiten mit großer Wirkung. Die erste ist der Statuscode: Wer etwas anlegt, antwortet nicht mit einer allgemeinen Erfolgsmeldung, sondern mit dem Code für "wurde erstellt".

5:37 Das ist keine Förmlichkeit — Werkzeuge, Caches und Client-Bibliotheken werten das aus. Die zweite ist die Transaktionsgrenze. Sie steht als Annotation an der Methode, und damit ist klar, wo sie beginnt und endet. Und beachten Sie, was zurückgegeben wird: dasselbe Objekt, aber jetzt mit einer ID, die aus der Datenbank kommt.

5:57 Der Aufrufer weiß danach, wie das angelegte Ding heißt — und muss nicht raten oder nachfragen. Was passiert eigentlich, wenn es den angefragten Datensatz nicht gibt? Die falsche Antwort wäre eine leere Antwort mit Erfolgsmeldung — der Aufrufer denkt, alles sei gut gegangen, und arbeitet mit nichts weiter. Die richtige Antwort ist der Statuscode für "nicht gefunden".

6:19 Das Elegante an dieser Lösung: Sie bauen die Antwort nicht selbst zusammen, sondern werfen eine Ausnahme, die das Framework kennt und in genau diesen Code übersetzt. Ihre Methode bleibt dadurch lesbar — sie beschreibt den Normalfall und meldet die Abweichung. Das ist ein Muster, das Sie in jedem Endpunkt wiederverwenden werden.

6:39 Jetzt sind Sie dran, und der spannende Teil ist nicht das Tippen. Bei den Anbietern gibt es zwei Suchparameter — Name und Mailadresse. Was passiert, wenn jemand beide angibt? Diese Frage hat keine technisch richtige Antwort, sie ist eine Design-Entscheidung. Sie können den zweiten ignorieren, einen Fehler melden oder beide kombinieren.

6:59 Alles drei ist vertretbar, solange es dokumentiert und vorhersehbar ist. Was nicht geht, ist der Zustand, den man in der Praxis am häufigsten findet: dass es einfach passiert, ohne dass jemand darüber nachgedacht hat. Treffen Sie eine Entscheidung — und schreiben Sie sie auf. Für den kombinierten Fall brauchen wir eine eigene Suche, und hier sehen Sie, was ich in Modul zwei angekündigt habe: Panache schenkt Ihnen die Standardfälle und lässt Ihnen die Sonderfälle.

7:26 Bemerkenswert ist die Art, wie die Werte in die Abfrage kommen — über benannte Parameter, nicht durch Zusammenkleben von Zeichenketten. Das ist kein Stilfrage, sondern Sicherheit: Zusammengesetzte Abfragen sind der Weg, auf dem seit Jahrzehnten SQL-Injection funktioniert. Der Aufwand ist derselbe, das Risiko nicht. Gewöhnen Sie es sich an, dann müssen Sie später nicht darüber nachdenken.

7:49 Und hier ist die Entscheidung von eben, ausformuliert. Wir haben uns für das Kombinieren entschieden: Sind beide Parameter da, muss beides passen. Schauen Sie auf die Reihenfolge der Prüfungen — erst der Fall ohne Angaben, dann der mit beiden, dann die Einzelfälle. Das ist dieselbe Regel wie bei FizzBuzz in Modul eins: Der spezifischere Fall gehört nach oben, sonst kommt er nie zum Zug. Damit steht Ihre Schnittstelle.

8:13 Im nächsten Modul zeigen wir dieselben Daten noch einmal — auf einem ganz anderen Weg, bei dem der Aufrufer selbst bestimmt, was er bekommt.