Übungsaufgaben zu Representational State Transfer (ReST)
https://bildung.social/@oerinformatik/111336676803320765
https://oer-informatik.de/rest-uebung
tl/dr; (ca. 30 min Bearbeitungszeit): Aufgaben zu den Grundlagen von ReST: Zunächst ein paar allgemeine Leitfragen zu Begriffen und Konzepten, dann zwei Fallbeispiele (API einer smarten Heizung und eines Industrieroboters), anhand derer das Grundlagenverständnis für ReST-Schnittstellen abgeprüft werden kann. (Zuletzt geändert am 01.11.2023)
Sämtliche Fragen beziehen sich auf die ReST-Grundlagen, wie sie in diesem Artikel beschrieben sind.
1. Leitfragen zu ReST-APIs
Was wird im ReST-Kontext unter einer Ressource verstanden?
Was versteht man im Rahmen von ReST unter einer Represenation?
Was unterscheidet eine URL von einer URI und von einer URN? Nenne jeweils Beispiele!
Welche HTTP-Methoden realisieren jeweils die vier Verantwortlichkeiten einer
CRUD-Schnittstelle?Welche Garantien bieten die HTTP-Methoden für
CRUD-Operationen?Welche Aufgabe übernimmt die HTTP-Methode
HEAD?Was versteht ReST unter dem Begriff “Hypermedia”?
ReST-APIs antworten auf Requests immer auch mit Statuscodes (wie alle HTTP-Responses). Wie lassen sich die Gruppen der 100er, 200er, 300er, 400er und 500er Statuscodes jeweils bezeichnen (mit Verweis auf die Eigenschaft der Reaktion der API)?
2. ReST-API für eine smarte Heizungsanlage
Die Steuerung einer Heizung bietet einen ReST-Service, der vom Raumthermostat zum Einlesen und Schreiben von Daten genutzt wird. Ein Kollege übergibt Dir seine Entwürfe der Endpunkte dieser API zum Review, und bittet Dich, die Beispielaufrufe zu verifizieren und zu kommentieren. Erläutere für jeden Aufruf, ob er ReST-konform ist (falls nein: warum nicht), welche CRUD-Funktion der Aufruf übernimmt und welche Garantien die genutzte HTTP-Methode bieten sollte, um HTTP/ReST-konform zu sein.
Hinweis: Die Syntax des Befehls spielt hier keine Rolle. Relevant sind nur die hervorgehobenen genutzte HTTP_METHODE, die Werte, die als BODY übergeben werden (optional) sowie die aufgerufene URL_DES_ENDPUNKS. Der schematische Aufbau von curl ist folgender:
Änderung der aktuellen Heizgrenztemperatur (auf 18.5 \rm{^{\circ}C}) für den Raum 1:
Wird mit diesem Aufruf eine fachgerecht entworfene ReST-Schnittstelle angesprochen? Falls nein: warum nicht?
Es handelt sich um einen fachgerechten ReST-Aufruf. Die HTTP-Methode
POSTkann zur Aktualisierung einer Ressource genutzt werden.Die genutzte Methode dieses Aufrufs bietet folgende Garantien:
POSTbietet keinerlei Garantien (ist also weder safe, cachable noch idempotent).Auslesen aller Informationen für den Raum 1:
Wird mit diesem Aufruf eine fachgerecht entworfene ReST-Schnittstelle angesprochen? Falls nein: warum nicht?
Es handelt sich um einen fehlerhaften ReST-Aufruf. Die HTTP-Methode
GETerwartet keinen Nachrichten-Body. BeiGET-Requests wird die ID der Ressource über die URL übergeben. Korrekt wäre etwaDie genutzte Methode dieses Aufrufs bietet folgende Garantien:
GET-Requests bietet alle drei Garantien, sie sind also safe, cachable und idempotent.Löschen der letzten eingegebenen Temperatur
Wird mit diesem Aufruf eine fachgerecht entworfene ReST-Schnittstelle angesprochen? Falls nein: warum nicht?
Es handelt sich um keinen korrekten Aufruf einer ReST-Schnittstelle. Da ReST zustandslos ist, verfügt es nicht über die Kenntnis, von welchem Zustand der Client derzeit ausgeht (anders, als bei Schnittstellen, die aktiv eine Session pflegen). Daher können Ressourcen nicht über relative Verweise wie next, previous oder last angesprochen werden.
Ausserdem muss eine ReST-Schnittstelle den
DELETE-Request idempotent umsetzen: mehrmaliges ausführen darf nur dieselben Seiteneffekte (Löschung) haben, wie einfaches ausführen. Würde ich immer den letzten Eintrag löschen, wären nach zwei identischen Requests auch zwei Einträge gelöscht.Die genutzte Methode dieses Aufrufs bietet folgende Garantien:
DELETE-Requests sind idempotent. Die Garantien safe und cachable bieten sie jedoch nicht.Ändern der Prognosewerte für die Folgewoche
Wird mit diesem Aufruf eine fachgerecht entworfene ReST-Schnittstelle angesprochen? Falls nein: warum nicht?
Der Aufruf ist fachgerecht. Auf diese Weise kann ein Wert aktualisiert werden.
Die genutzte Methode dieses Aufrufs bietet folgende Garantien:
PUT-Requests sind idempotent. Die Garantien safe und cachable bieten sie jedoch nicht.Beschreibe in einem Satz, was man im Rahmen von ReST unter “Zustandslosigkeit” versteht!
Alle Informationen, die zur Verarbeitung benötigt werden, werden mit dem Aufruf übergeben. Es gibt keine Session-Variablen und keinen lokalen Zustand, auf den sich die Aufrufe beziehen.
3. ReST-API für einen Industrieroboter
Für einen Industrieroboter, der Produkte lackiert, soll ein ReST-Service erstellt werden. Über die ReST-Schnittstelle sollen bestimmte Positionen festgelegt und angefahren werden können. Außerdem sollen die Farbwerte darüber beeinflusst und ausgelesen werden können. Ein Fragment des Services besteht bereits, das jetzt verfeinert werden soll.
Hinweis: Die Aufrufe der ReST-API erfolgen beispielhaft über die Konsole (Windows PowerShell, das Commandlet Invoke-WebRequest entspricht curl unter Linux). Bei einem solchen Aufruf wird die Art des Requests (HTTP_METHODE) und die URL zur Ressource (URL_ZU_DER_RESSOURCE) wie in folgendem Beispiel übergeben. Bei Bedarf kann noch ein Nachrichtenpayload (BODY_DES_REQUESTS) und das zugehörige Datenformat (CONTENT_TYPE_STRING) übergeben werden:
Die Aufgaben sind möglicherweise schwer verständlich, wenn bislang nicht mit kleinen Robotersystemen wie z.B. Dobots gearbeitet und deren API programmiert wurde. Üblich ist bei solchen Robotern, dass Positionen als dreidimensionale Koordinaten gespeichert werden (z.B. AUFNAHMEPOS könnte für den Wert x=123, y=234, z=134 stehen).
Die Art der Authentifizierung und Autorisierung spielt bei den folgenden Fragen keine Rolle.
Eine fertige Komponente der ReST-Schnittstelle des Roboters kann über die Powershell mit folgendem Befehl angesprochen werden:
Welche Reaktion oder Ausgabe erwartest Du beispielhaft vom System bei einem derartigen Aufruf? Beziehe Dich in Deiner Antwort auch auf den ReST-Begriff Repräsentation.
Man erwartet von dieser Art Request die Rückgabe der Werte der Position AUFNAHMEPOS in einer Repräsentationsform, z.B. als JSON:
gegebenenfalls (wenn auch weniger üblich) als CSV, XML oder beliebiger anderer Form, die die API als Standard implementiert hat.
Eine Kollegin / ein Kollege hat den folgenden Endpunkt programmiert, mit dem der Roboterarm zu einer benannten und gespeicherten Stelle bewegt werden kann. Er/Sie führt dir vor, wie praktisch man nun den Roboterarm positionieren kann (nach diesem Request bewegt sich der Arm auf die gewünschte Position):
Bewerte den Vorschlag hinsichtlich der Grundlagen von ReST-Schnittstellen und schlage ggf. eine Alternative vor.
GET-Requests müssen grundsätzlich safe sein, dürfen das System also nicht verändern. Durch die Bewegung des Arm verändert sich der Zustand des Systems aber nachhaltig. Da es sich um eine Änderung des Zustands handelt (UPDATE) wärePUTdas korrekte HTTP-Verb für den Request. Allerdings sollte der neue Zustand im Body übergeben werden, da die URL nur die Ressource anspricht. Denkbar wäre ein Request wie:Beschreibe, welche Reaktion des Systems Du beim folgenden Aufruf erwartest:
Invoke-RestMethod http://roboter.firma.de:8085/api/farbsaettigung -Method 'PUT' -ContentType 'application/json; charset=utf-8' -Body '{"min":60, "max":80}'Die Ressource farbsaettigung wird hier geänder (geupdatet) und hat fortan einen neuen Wert.
Beschreibe, welche Reaktion des Systems Du beim folgenden Aufruf erwartest:
Invoke-RestMethod http://roboter.firma.de:8085/api/position/ -Method 'POST' -ContentType 'application/json; charset=utf-8' -Body '{"name":"RUHEPOS", "x":60, "y":80, "z":80}'Es wird eine neue Ressource erzeugt, die die übergebenen Parameter hat.
HTTP-Methoden bieten unterschiedliche Garantien/Eigenschaften. Nenne die drei wesentlichen Garantien und ordne zu, welche Garantien die Aufrufe oben von
GETPUTundPOSTbietenCacheable Idempotent Safe GET ja ja ja PUT nein ja nein POST nein nein nein Was versteht man unter einer URI? Nenne beispielhaft eine URI der Lacker-Roboter-ReST-API!
Mit einer URI wird eine Ressource (eine Entität der API) eindeutig identifiziert. Die oben beschriebene API verwendet als URI URLs wie
http://roboter.firma.de:8085/api/position/RUHEPOS
Links und weitere Informationen
Wer es genau wissen will: die ReST Architektur basiert auf einer Dissertation von Roy Thomas Fielding mit dem Titel Architectural Styles and the Design of Network-based Software Architectures
Hauptquelle für Informationen zu ReST ist die HTTP1.1 Spezifikation, festgeschrieben in der RFC-2616 (link)
Hinweis zur Nachnutzung als Open Educational Resource (OER)
Dieser Artikel und seine Texte, Bilder, Grafiken, Code und sonstiger Inhalt sind - sofern nicht anders angegeben - lizenziert unter CC BY 4.0. Nennung gemäß TULLU-Regel bitte wie folgt: “Übungsaufgaben zu Representational State Transfer (ReST)” von Hannes Stein, Lizenz: CC BY 4.0. Der Artikel wurde unter https://oer-informatik.de/rest-uebung veröffentlicht, die Quelltexte sind in weiterverarbeitbarer Form verfügbar im Repository unter https://gitlab.com/oer-informatik/java-springboot/rest. Stand: 01.11.2023.
[Kommentare zum Artikel lesen, schreiben] / [Artikel teilen] / [gitlab-Issue zum Artikel schreiben]
