Praktikumsversuch Representational State Transfer (REST) und CORS

Dieses Praktikum dient dem Verständnis des REST-Paradigmas und der praktischen Erprobung einer REST-API.

Vorbereitung

Was bedeutet die Abkürzung HATEOAS?
Was zeichnet eine sinnvolle REST-API aus?

REST-API Prinzipien

Adressierung von Ressourcen per URL
intensive Verwendung des HTTP-Protokolls (mehrere Methoden)
- GET: fordert Ressource an
- POST: erstellt neue Sub-Ressource, Rückgabe der Adresse der neuen Ressource (nicht idempotent)
- PUT: Ressource update (anlegen oder ändern)
- PATCH: teilweises update
- DELETE: Löscht Ressource
- OPTIONS:
Repräsentation von Daten/Nachrichten (HTML, JSON, XML)
selbstbeschreibende Nachrichten
Entwurfsprinzip: Hypermedia as the Engine of Application State (Navigation über vom Server bereitgestellte URLs)

HATEOAS

Die Server-Antwort sollte Weiterverfolgungs-Links enthalten, z.B. nach GET-Request eines Quiz alle möglichen Folgeaktionen:

"_links": {
            "self":     { "href": "/api/quizzes/123" },
            "solve":    { "href": "/api/quizzes/123/solve", "method": "POST" },
            "update":   { "href": "/api/quizzes/123", "method": "PUT" }
            "delete":   { "href": "/api/quizzes/123", "method": "DELETE" }
            "completed":{ "href": "/api/quizzes/completed", "method": "GET" }
        }
        
        

Das Ziel ist eine weitgehende Entkopplung des Clients von der Server-API. Arten der Umsetzung:

HAL-Format (Hypertext Application Language): Einfach zu implementieren. Es fügt lediglich Links und eingebettete Ressourcen hinzu (keine Infos über POST-Felder oder Methoden). Basiert im Wesentlichen auf zwei reservierten Feldern:
- ` _links-Objekt`: alle Hyperlinks, welche von der aktuellen Ressource erreichbar sind
- _embedded-Objekt: einbetten von verwandten Ressourcen direkt in der Antwort
- Media Type: application/hal+json
- reines HAL liefert nur URLs ohne Methodenbeschreibung, Erweiterung: HAL-FORMS (_templates)
JSON:API: Durch “Sparse Fieldsets” und “Included Resources” kannst man genau die Daten anfordern, die man brauchst. Ressourcen werden flach in einem included-Array geliefert, was Redundanz vermeidet.
Siren: Geht bei HATEOAS am weitesten. Es enthält ein actions-Array. Hier steht nicht nur eine URL, sondern auch, welche Felder (name, type) ein Client für einen POST-Request mitschicken muss. Der Client kann so dynamisch Formulare generieren.

Same-Origin Policy (SOP)

Zur Verhinderung von unerwünschten Zugriffen (Cross-Site Request Forgery) zwischen verschiedenen Hosts (Origins) gilt für clientseitige Skriptsprachen die Same-Origin-Policy (SOP).
Für einen erlaubten Zugriff müssen folgende Parameter identisch sein: Protokoll, Hostname, Port

Für viele (verteilte) Anwendungen ist die Begrenzung von SOP unpraktisch, hier hilft CORS
- Steuerung des Skript-Zugriffs von fremden Domänen
- Steuerung über HTTP-Header: Access-Control-Allow-Origin: “erlaubter Host” (* für beliebige Herkunft)
  - Asterisk und Credentials
  - häufig eingesetzter Workaround: dynamische Erzeugung der Allow-Origin ja nach Origin des Requests
- WebQuiz ist mit Asterisk für beliebige Herkunft konfiguriert.
- Zur Prüfung des korrekten Zugriffs nutzt ein Browser einen sogenannten Preflight-Check.

Aufgaben

Wir nutzen für unserer Versuche CURL und die API des WebQuiz-Server auf Server idefix.

Registrieren Sie einen neuen Nutzer (diesen können Sie später für den Beleg weiter nutzen)
Erzeugen Sie einige neue Quiz mit 4 Optionen und einer korrekten Antwort, notieren Sie die zurückgegebenen IDs
Rufen Sie ein erstelltes Quiz per ID ab
Lösen Sie das erhaltene Quiz
experimentieren Sie mit dem Paging (erhalten aller Quiz in einer Antwort)
Empfangen Sie alle gelösten Quiz
Löschen Sie eines Ihrer Quiz, probieren Sie nicht vergebene IDs und IDs von anderen Nutzern
Hinweis: Sie können die CURL-Kommandos auch in ein BASH-Script einbetten

API WebQuiz

Base-URL: https://hostname:8888/api/ (der konkrete Hostname wird im Praktikum bekanntgegeben)
Web-Zugriff auf die Datenbank: /api/h2-console
Format für alle gesendeten und empfangenen Daten: Content-Type: application/json

Vorgang	Methode	URL (/api/…)	Daten (JSON)	Antwort (JSON)	HTTP	Auth.	Eig.
Register new user	POST	`register`	`email, password`		200, 400
Create a quiz	POST	`quizzes`	`title, text, options, answer`	id, title, text, options	200, 404	x
Get a quiz	GET	`quizzes/id`		id, title, text, options	200, 404	x
Get all quizzes	GET	`quizzes?page=0`		Array	200	x
Solving a quiz	POST	`quizzes/id/solve`	`[0,1]`	success, feedback	200, 404	x
Get all completed quizzes	GET	`quizzes/completed`		Array	200	x
Deleting a quiz	DELETE	`quizzes/id`			204, 403, 404	x	x

Für welchen Vorgang würden Sie die Methode PUT verwenden?
Entspricht diese API dem HATEOAS-Prinzip?
Was würden Sie ändern?

CURL

GET : curl -X GET http://localhost:8888/api/quizzes/1
POST: curl -X POST http://localhost:8888/api/register
Header: -H "Content-Type: application/json"
DATA:
- JSON: --data '{"email":"test@gmail.com", "password": "secret"}' http://localhost:8888/api/quizzes
- JSON-ARRAY: --data '[1, 2]'
- -d '{"title":"The Java Logo", "options": ["Robot", "Tea leaf", "Cup of coffee", "Bug"], "answer": [2]}'
Authentification: --user test@gmail.com:secret

Literatur

Fakultativ

Zugriff mittels JavaScript

Rufen Sie ein Quiz mittels IP ab und stellen es in der Konsole dar.
Schicken Sie die Antwort zum Quiz an den Server und stellen Sie die Antwort dar.

Rechnernetze / Kommunikationssysteme