Aufgabe 15 - Ressourcenschnitt für das eigene Projekt

Aufgabe 15 - Ressourcenschnitt für das eigene Projekt

Worum geht es?

Sie leiten aus Ihrer Domänenskizze die Schnittstelle Ihres Projekts ab: welche Ressourcen es gibt, welche Methoden darauf erlaubt sind, wer sie aufrufen darf und welche Fehler auftreten können (siehe Kapitel Schnittstellen im Vergleich). Implementiert wird nichts. Was hier entsteht, ist eine Tabelle, und genau diese Tabelle erspart Ihnen in Kapitel 7 den Umbau.

Was Sie dafür brauchen

• Kapitel Schnittstellen im Vergleich, Abschnitte Ressourcen statt Aktionen bis Statuscodes und Entwurf für das eigene Projekt.
• Die Domänenskizze aus Aufgabe 02 und die Rollen aus Aufgabe 01.
• Die beiden Regeln aus Aufgabe 14.

Welche Kompetenzen Sie erwerben und zeigen

• Sie überführen einen aktionsorientierten Entwurf in einen ressourcenorientierten.
• Sie ordnen jeder Ressource Methoden, Statuscodes und erlaubte Rollen zu.
• Sie modellieren Zustandsübergänge, ohne Verben in die URL zu schreiben.

Pädagogische Einordnung

• Reproduktion: aktionsorientierte Pfade in ressourcenorientierte umschreiben (Teil A).
• Reorganisation und Transfer: die eigene Domänenskizze in eine Endpunktliste überführen (Teil B).
• Reflexion, Problemlösung und Urteilsbildung: Sonderfälle und Fehlerfälle festlegen und den Entwurf prüfen lassen (Teil C).

Arbeitsaufträge

Die Übung ist auf etwa zwei Stunden ausgelegt.

Teil A - Aktionen in Ressourcen übersetzen

1. Schreiben Sie die folgenden acht Aufrufe in eine ressourcenorientierte Form um. Notieren Sie jeweils Methode, Pfad und den Statuscode, mit dem der Server bei Erfolg antwortet:

   • POST /getBookings
   • POST /createBooking
   • POST /deleteBooking?id=42
   • GET /bookingsOfMachine?m=7
   • POST /updateUserEmail
   • GET /searchMachines?q=fraese
   • POST /listOpenSlots
   • POST /markBookingAsPaid

2. Zwei dieser acht lassen sich auf mehr als eine sinnvolle Art umschreiben. Suchen Sie sie und beschreiben Sie zu jedem beide Möglichkeiten in je einem Satz.

3. Erklären Sie in drei bis vier Sätzen, warum DELETE /bookings/42 gegenüber POST /deleteBooking?id=42 im Betrieb einen Unterschied macht. Gehen Sie darauf ein, was beim zweiten Aufruf passiert, wenn die Verbindung abbricht und der Client es noch einmal versucht.

4. Legen Sie eine Tabelle der sechs HTTP-Methoden an, mit den Spalten Methode, sicher, idempotent, typische Verwendung. Füllen Sie sie aus dem Gedächtnis aus und prüfen Sie danach gegen das Kapitel.

Teil B - Die eigene Endpunktliste

1. Nehmen Sie Ihre Domänenskizze und schreiben Sie alle Entitäten als Substantive auf. Entscheiden Sie zu jeder, ob sie eine eigene Ressource wird oder ein Feld einer anderen bleibt. Was nie einzeln adressiert wird, bleibt ein Feld. Begründen Sie jede Entscheidung in einem halben Satz.

2. Legen Sie für Ihre Ressourcen die Pfade fest: Sammlung, einzelnes Element, und wo sinnvoll Unterressourcen für Beziehungen. Schreiben Sie sie untereinander auf.

3. Bauen Sie die Endpunkttabelle Ihres Projekts nach dem Vorbild im Kapitel, mit den Spalten Methode und Pfad, Zweck, Erfolg, Fehler, erlaubte Rollen. Acht bis zwölf Zeilen sind ein guter Umfang.

4. Die Spalte mit den erlaubten Rollen ist der Vorgriff auf Kapitel 8. Füllen Sie sie für jede Zeile aus. Wenn Ihnen dabei eine Rolle fehlt, die es im Datenmodell noch nicht gibt, notieren Sie das gesondert.

5. Prüfen Sie jede Zeile gegen zwei Fragen: Steckt ein Verb im Pfad? Und ist der Erfolgscode wirklich der passende, also 201 mit Location beim Anlegen und 204 beim Löschen? Bessern Sie nach.

6. Prüfen Sie Ihre Tabelle gegen die beiden Regeln, die Sie aus Aufgabe 14 mitgebracht haben. Notieren Sie, ob Ihr eigener Entwurf sie einhält.

Teil C - Sonderfälle, Fehler und Gegenlesen

1. Suchen Sie in Ihrem Projekt zwei Vorgänge, die kein Ding sind, sondern ein Zustandsübergang: eine Stornierung, eine Freigabe, ein Versand, eine Bestätigung. Entscheiden Sie zu jedem zwischen den beiden Wegen aus dem Kapitel, also Unterressource oder Feldänderung per PATCH. Begründen Sie die Wahl in je zwei bis drei Sätzen und halten Sie sich an die Regel, nicht beides gleichzeitig anzubieten.

2. Legen Sie für jede Zeile Ihrer Tabelle mindestens einen Fehlerfall fest, bevor irgendetwas implementiert wird. Achten Sie darauf, dass 400, 401, 403, 404, 409 und 422 jeweils mindestens einmal vorkommen und jeweils zum Anlass passen.

3. Suchen Sie in Ihrem Projekt eine Stelle, an der zwei Personen gleichzeitig dasselbe ändern könnten. Beschreiben Sie in vier bis fünf Sätzen, was ohne Gegenmaßnahme passiert, und ergänzen Sie in Ihrer Tabelle die Spalte für ETag und If-Match samt dem Statuscode, mit dem der Server den Konflikt meldet.

4. Legen Sie drei Festlegungen für Ihre Datenformate schriftlich fest: das Format für Datum und Zeit, die Darstellung von Geldbeträgen falls vorhanden, und die Behandlung langer IDs. Begründen Sie jede in einem Satz und legen Sie alle drei in docs/architektur.md ab.

5. Machen Sie die Probe aus dem Kapitel. Geben Sie eine Beispielantwort Ihrer geplanten Schnittstelle jemandem aus einer anderen Gruppe, ohne Erklärung. Notieren Sie jede Stelle, die diese Person nicht auf Anhieb richtig deutet. Jede davon ist eine Lücke in Ihrem Vertrag.

6. Bessern Sie die gefundenen Lücken aus und notieren Sie, was Sie geändert haben.

Wissenscheck

1. Woran erkennen Sie, dass ein Pfad aktionsorientiert statt ressourcenorientiert ist?
2. Wann wird aus einer Entität eine eigene Ressource, wann bleibt sie ein Feld?
3. Welche zwei Wege gibt es für einen Zustandsübergang, und warum bietet man nicht beide gleichzeitig an?
4. Welcher Statuscode gehört zum erfolgreichen Anlegen, und welche Kopfzeile gehört dazu?
5. Was ist ein Lost Update, und wie verhindern ETag und If-Match es?
6. Warum gehören Geldbeträge nicht in Gleitkommazahlen, und was nimmt man stattdessen?
7. Warum werden lange Datenbank-IDs als Zeichenkette übertragen?

Abgabe

Die Endpunktliste Ihres Projekts als Tabelle mit Methode, Pfad, Zweck, Erfolgs- und Fehlercodes und erlaubten Rollen, abgelegt in docs/architektur.md. Dort stehen ebenfalls die drei Festlegungen zu Datum, Geld und IDs. In protokoll.md stehen die Übersetzungen aus Teil A, die Begründungen zu den Zustandsübergängen und die Befunde aus der Probe in Teil C.