[Ausbildung] Grundlagen REST

Die Auszubildenden sollen das Konzept REST kennenlernen und das Prinzip dahinter verstehen. Aufbauend auf dieser Kenntnis werden dann bekannte Beispiele betrachtet.
Abgeschlossen wird mit der praktischen Dokumentation einer REST-Schnittstelle mittels Swagger.

Voraussetzungen

Laptop

Dauer

1 Tag

Themen

REST, Schnitstellen, HTTP, Swagger

Ablauf

REST – Was ist das?

Representational State Transfer (abgekürzt REST, seltener auch ReST) bezeichnet ein Programmierparadigma für verteilte Systeme, insbesondere für Webservices. REST ist eine Abstraktion der Struktur und des Verhaltens des World Wide Web. REST hat das Ziel, einen Architekturstil zu schaffen, der die Anforderungen des modernen Web besser darstellt. Dabei unterscheidet sich REST vor allem in der Forderung nach einer einheitlichen Schnittstelle (siehe Abschnitt Prinzipien) von anderen Architekturstilen.

Der Zweck von REST liegt schwerpunktmäßig auf der Maschine-zu-Maschine-Kommunikation. REST stellt eine einfache Alternative zu ähnlichen Verfahren wie SOAP und WSDL und dem verwandten Verfahren RPC dar. Anders als bei vielen verwandten Architekturen kodiert REST keine Methodeninformation in den URI, da der URI Ort und Namen der Ressource angibt, nicht aber die Funktionalität, die der Web-Dienst zu der Ressource anbietet. Der Vorteil von REST liegt darin, dass im WWW bereits ein Großteil der für REST nötigen Infrastruktur (z. B. Web- und Application-Server, HTTP-fähige Clients, HTML- und XML-Parser, Sicherheitsmechanismen) vorhanden ist, und viele Web-Dienste per se REST-konform sind. Eine Ressource kann dabei über verschiedene Medientypen dargestellt werden, auch Repräsentation der Ressource genannt.

So ist ein Online-Dienst, der lediglich unveränderte Seiteninhalte nach dem Internetstandard HTTP anbietet, bereits REST-konform. Dynamisch erzeugte Seiten folgen diesem Paradigma jedoch oft nicht. So bieten beispielsweise Nachrichtenseiten sich ständig ändernde Informationen mit sowohl unterschiedlichem Format als auch Inhalt an, die nur schwer automatisch verarbeitet werden können. Bliebe das Format unverändert, so wäre eine wichtige REST-Eigenschaft erfüllt. So wäre eine Webseite, auf der ständig die aktuelle Uhrzeit in immer demselben Format abrufbar ist, REST-konform.

Die Bezeichnung „Representational State Transfer“ soll den Übergang vom aktuellen Zustand zum nächsten Zustand (state) einer Applikation verbildlichen. Dieser Zustandsübergang erfolgt durch den Transfer der Daten, die den nächsten Zustand repräsentieren.

Kopiert von https://de.wikipedia.org/wiki/Representational_State_Transfer

Prinzipien

Der Architektur-Stil verweist auf sechs Eigenschaften, die ein Dienst haben muss. Dabei ist nicht festgelegt, wie diese Prinzipien implementiert werden müssen.

Client-Server

Es gilt generell die Anforderung, dass alle Eigenschaften der Client-Server-Architektur gelten. Dabei stellt der Server einen Dienst bereit, der bei Bedarf vom Client angefragt werden kann.

Zustandslosigkeit

Jede REST-Nachricht enthält alle Informationen, die für den Server bzw. Client notwendig sind, um die Nachricht zu verstehen. Weder der Server noch die Anwendung soll Zustandsinformationen zwischen zwei Nachrichten speichern. Man spricht daher von einem zustandslosen (englisch: stateless) Protokoll. Jede Anfrage eines Clients an den Server ist insofern in sich geschlossen, als sie sämtliche Informationen über den Anwendungszustand beinhaltet, die vom Server für die Verarbeitung der Anfrage benötigt werden.
Zustandslosigkeit in der hier beschriebenen Form begünstigt die Skalierbarkeit eines Webservice. Beispielsweise können eingehende Anfragen im Zuge der Lastverteilung unkompliziert auf beliebige Maschinen verteilt werden: Da jede Anfrage in sich geschlossen ist und Anwendungsinformationen somit ausschließlich auf der Seite des Clients vorgehalten werden, ist auf der Seite des Servers keine Sitzungsverwaltung erforderlich. In der Praxis nutzen deswegen viele HTTP-basierte Anwendungen Cookies und andere Techniken, um Zustandsinformationen auf der Client-Seite zu behalten. Weiterhin begünstigt wird die Ausfallsicherheit, weil die Zustandslosigkeit fordert, dass transaktionale Datenübertragung in einem einzigen Seitenaufruf erfolgt.

Caching

HTTP Caching soll genutzt werden, wobei aber gilt: Eine Anfrage, die nicht gestellt werden muss, ist die schnellste Anfrage.

Einheitliche Schnittstelle

Dies ist das Hauptunterscheidungsmerkmal von allen weiteren Architekturstilen. Dabei besteht diese aus vier weiteren Eigenschaften. Ziel ist die Einheitlichkeit der Schnittstelle und somit ihre einfache Nutzung.

Adressierbarkeit von Ressourcen

Jede Information, die über einen URI kenntlich gemacht wurde, wird als Ressource gekennzeichnet. Jeder REST-konforme Dienst hat eine eindeutige Adresse, den Uniform Resource Locator (URL). Diese „Straße und Hausnummer im Netz“ standardisiert den Zugriffsweg zum Angebot eines Webservices für eine Vielzahl von Anwendungen (Clients). Eine konsistente Adressierbarkeit erleichtert es außerdem, einen Webservice als Teil eines Mashupsweiterzuverwenden.

Repräsentationen zur Veränderung von Ressourcen

Die unter einer Adresse zugänglichen Dienste können unterschiedliche Darstellungsformen (Repräsentationen) haben. Ein REST-konformer Server kann je nachdem, was die Anwendung anfordert, verschiedene Repräsentationen einer Ressource ausliefern, z. B. in verschiedenen Sprachen oder Formaten (HTML, JSON oder XML) oder auch die Beschreibung oder Dokumentation des Dienstes. Die Veränderung einer Ressource (also deren aktuellen Status) soll nur über eine Repräsentation erfolgen.

Selbstbeschreibende Nachrichten

REST-Nachrichten sollen selbstbeschreibend sein. Dazu zählt u. a. die Verwendung von Standardmethoden. Über diese Standardmethoden lassen sich Ressourcen manipulieren. Als Beispiel seien an dieser Stelle die HTTP-Verben genannt; Details siehe unten.

Kopiert von https://de.wikipedia.org/wiki/Representational_State_Transfer#Prinzipien

Beispiele

Zusammen mit den Auszubildenden werten 2 Beispiele durchgegangen.

Hier werden die Prinzipien gesucht und besprochen.

Beispiel Webseite

Eine beliebige Webseite (zB diese hier) wird besucht.

Die Prinzipien:

Prinzip	Erklärung
Client-Server	Webseite -> Server Mein PC -> Client
Zustandslosigkeit	Ich kann jederzeit auf jede Seite zugreifen, muss mich nicht anmelden, Abfragen vorneweg stellen…
Caching	Mal in den Developertools schauen
Adressierbarkeit von Ressourcen	Das Prinzip des Internets und von Links

Beispiel Twitter API

https://dev.twitter.com/rest/tools/console

Dazu die Frage: Finden wir auch hier die Prinzipien wieder?

Herausforderungen

Natürlich gibt es auch bei REST, wie bei jedem Konzept Herausforderungen, die gelöst werden müssen:

Viele mögliche Zugriffe
Wie heißen die Pfade?
Query-Parameter?
Beim POST: Wie sieht das aus?
Muss ich Header mitgeben?

Dokumentation mittels Swagger

Eine Lösung kann sein, die Schnittstelle genau zu Beschreiben. Helfen kann dabei zB Swagger.

Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

Kopiert von Swagger.io

Mittels 2 Webseite sollen hier Grundlagen vermittelt werden:

Wenn anschließend noch Zeit verfügbar ist, kann als Übung die Übung „Ein erstes node.js Plattenlabel“ mittels Swagger dokumentiert werden