Aufgabe
Ausgangssituation
Ihr Ausbildungsbetrieb entwickelt für eine Fahrradvermietung die Anwendung MietStation. Über eine REST-Schnittstelle sollen externe Partner-Apps (z. B. eine Stadtplan-App) auf die Mietstationen und deren Fahrräder zugreifen können. Sie sind im Projektteam für die Spezifikation und Qualitätssicherung dieser Schnittstelle zuständig.
Die folgende Tabelle zeigt einen Auszug aus der bestehenden API-Dokumentation:
| Endpunkt | HTTP-Methode | Beschreibung | Rückgabe bei Erfolg |
|---|---|---|---|
/stationen | GET | Liste aller Stationen abrufen | 200 OK |
/stationen/{id} | GET | Einzelne Station abrufen | 200 OK |
/stationen | POST | Neue Station anlegen | 201 Created |
/stationen/{id} | PUT | Station vollständig aktualisieren | 200 OK |
/stationen/{id} | DELETE | Station löschen | 204 No Content |
Ein Kollege hat testweise folgende JSON-Antwort für den Aufruf GET /stationen/7 erzeugt:
{
"id": 7,
"name": "Hauptbahnhof Nord",
"kapazitaet": 20,
"freiePlaetze": 5,
"fahrraeder": [
{ "radId": "R-101", "typ": "Cityrad", "akkuProzent": 88 },
{ "radId": "R-102", "typ": "E-Bike", "akkuProzent": 42 }
],
"aktiv": true
}
Beim Testen der Schnittstelle mit einem API-Testwerkzeug wurden folgende Anfragen protokolliert:
| Nr. | Anfrage | Server-Antwort (Statuscode) |
|---|---|---|
| 1 | GET /stationen/99 | 404 |
| 2 | POST /stationen (fehlerhafter JSON-Body, Komma vergessen) | 400 |
| 3 | PUT /stationen/7 (ohne gültigen Zugriffstoken) | 401 |
| 4 | DELETE /stationen/7 (Nutzer ohne Löschrechte) | 403 |
| 5 | GET /stationen | 500 |
a) HTTP-Methoden und Statuscodes
aa) Methodeneigenschaften (4 Punkte)
Betrachten Sie die Tabelle mit den fünf Endpunkten. Erläutern Sie zwei Eigenschaften, in denen sich die Methode PUT von der Methode POST beim Zugriff auf den Endpunkt /stationen bzw. /stationen/{id} grundsätzlich unterscheidet.
ab) Statuscode-Analyse (3 Punkte)
Betrachten Sie die Protokolltabelle der fünf Anfragen. Erläutern Sie für die Anfragen Nr. 2, Nr. 4 und Nr. 5 jeweils, welche konkrete Ursache zu dem protokollierten Statuscode geführt hat.
b) JSON-Struktur bewerten (2 Punkte)
Betrachten Sie die oben gezeigte JSON-Antwort für GET /stationen/7. Beschreiben Sie zwei Mängel dieser JSON-Struktur in Bezug auf die Eindeutigkeit bzw. Erweiterbarkeit der Datenrepräsentation für externe Partner-Apps.
c) Neue Ressource entwerfen (9 Punkte)
Die Partner-Apps sollen künftig auch Buchungen für ein einzelnes Fahrrad an einer Station durchführen können. Eine Buchung enthält mindestens: eine eindeutige Buchungs-ID, die Stations-ID, die Rad-ID, den Zeitpunkt der Ausleihe, den Zeitpunkt der geplanten Rückgabe sowie einen Status (reserviert, aktiv, abgeschlossen, storniert).
Erstellen Sie eine vollständige REST-Spezifikation für die Verwaltung dieser Buchungen. Die Spezifikation muss enthalten:
- die passenden Endpunkte mit jeweiliger HTTP-Methode zum Anlegen, Abrufen (einzeln und als Liste), Aktualisieren des Status sowie Stornieren einer Buchung,
- für jeden Endpunkt den jeweils korrekten Erfolgs-Statuscode,
- ein Beispiel für den JSON-Request-Body beim Anlegen einer neuen Buchung,
- ein Beispiel für die JSON-Antwort beim Abrufen einer einzelnen Buchung.
d) Fehlerbehandlung konzipieren (2 Punkte)
Ein Partner möchte eine Buchung stornieren, deren Status bereits abgeschlossen ist. Nennen Sie zwei Bestandteile, die eine fachlich aussagekräftige Fehlerantwort des Servers in diesem Fall enthalten sollte.
▶Musterlösung anzeigen
Musterlösung
a) HTTP-Methoden und Statuscodes
aa) Methodeneigenschaften (4 Punkte)
- Idempotenz:
PUTist idempotent – wird dieselbe Anfrage an/stationen/{id}mehrfach gesendet, ist der Zustand der Ressource danach derselbe wie nach einem einzigen Aufruf.POSTist nicht idempotent – jede Wiederholung derselben Anfrage an/stationenlegt eine weitere Station an. (2 Punkte) - Adressierung und ID-Vergabe:
POSTrichtet sich an die Sammlung/stationen; der Server vergibt die ID der neuen Station und meldet sie mit 201 Created (üblicherweise samt Location-Header) zurück.PUTrichtet sich an eine konkrete, dem Client bekannte Ressource/stationen/{id}und ersetzt deren Darstellung vollständig. (2 Punkte)
ab) Statuscode-Analyse (3 Punkte)
- Nr. 2 – 400 Bad Request: Der JSON-Body ist syntaktisch ungültig (fehlendes Komma), der Server kann die Anfrage nicht verarbeiten. Die Ursache liegt beim Client. (1 Punkt)
- Nr. 4 – 403 Forbidden: Der Nutzer ist authentifiziert, besitzt aber keine Berechtigung zum Löschen. Abgrenzung: 401 Unauthorized steht für fehlende oder ungültige Authentifizierung (wie bei Nr. 3). (1 Punkt)
- Nr. 5 – 500 Internal Server Error: Die Anfrage selbst ist korrekt; die Ursache liegt auf dem Server, z. B. eine unbehandelte Ausnahme oder eine nicht erreichbare Datenbank. (1 Punkt)
b) JSON-Struktur bewerten (2 Punkte)
- Mangelnde Eindeutigkeit: Das Feld
akkuProzentist auch beim Typ „Cityrad“ belegt (88), sodass unklar bleibt, ob dieses Rad überhaupt einen Akku besitzt;typist Freitext ohne festgelegten Wertebereich. Zudem lassen sichkapazitaet(20), die zwei gelisteten Räder undfreiePlaetze(5) nicht nachvollziehen – ein redundant abgeleiteter Wert kann inkonsistent werden. (1 Punkt) - Eingeschränkte Erweiterbarkeit: Die Fahrräder sind vollständig eingebettet, ohne eigene Ressourcen-URI bzw. Verweis (z. B.
/stationen/7/fahrraeder) und ohne Paging; bei vielen Rädern wächst die Antwort unkontrolliert. Außerdem fehlen eine Versionierung und für eine Stadtplan-App wichtige Angaben wie Standortkoordinaten. (1 Punkt)
c) Neue Ressource entwerfen (9 Punkte)
Endpunkte mit HTTP-Methode und Statuscode:
| Endpunkt | HTTP-Methode | Beschreibung | Erfolgs-Statuscode |
|---|---|---|---|
/buchungen | POST | Neue Buchung anlegen | 201 Created |
/buchungen/{buchungId} | GET | Einzelne Buchung abrufen | 200 OK |
/buchungen | GET | Liste aller Buchungen abrufen | 200 OK |
/buchungen/{buchungId} | PATCH | Status einer Buchung aktualisieren (inkl. Stornieren durch Setzen von status='storniert') | 200 OK |
Begründung der Methodenwahl: Für das Anlegen wird POST auf die Sammlung /buchungen verwendet, da die Buchungs-ID serverseitig erzeugt wird. Für die Statusänderung – einschließlich des Stornierens – wird einheitlich PATCH verwendet, da in beiden Fällen nur das Statusattribut der bestehenden Ressource geändert wird und die Ressource selbst (inkl. Historie) erhalten bleiben muss. DELETE ist hier nicht geeignet, da DELETE das endgültige Entfernen der Ressource bedeutet und die Buchung nach Stornierung weiterhin unter ihrer ID abrufbar sein soll (Status 'storniert').
Beispiel Request-Body beim Anlegen (POST /buchungen):
{
"stationId": 7,
"radId": "R-102",
"ausleihZeitpunkt": "2024-06-01T09:30:00Z",
"geplanteRueckgabe": "2024-06-01T11:30:00Z"
}
Hinweis: Buchungs-ID und initialer Status ('reserviert') werden serverseitig vergeben und sind daher nicht Teil des Request-Bodys.
Beispiel Antwort beim Abrufen einer Buchung (GET /buchungen/4512):
{
"buchungId": 4512,
"stationId": 7,
"radId": "R-102",
"ausleihZeitpunkt": "2024-06-01T09:30:00Z",
"geplanteRueckgabe": "2024-06-01T11:30:00Z",
"status": "aktiv"
}
Beispiel Request-Body zum Stornieren (PATCH /buchungen/4512):
{
"status": "storniert"
}
d) Fehlerbehandlung konzipieren (2 Punkte)
- Einen aussagekräftigen Fehler-Statuscode, z. B. 409 Conflict, der anzeigt, dass die Anfrage (PATCH mit status='storniert') dem aktuellen Zustand der Ressource (status='abgeschlossen') widerspricht.
- Einen JSON-Fehlertext im Response-Body mit einer verständlichen Fehlermeldung, z. B. { "fehler": "Buchung bereits abgeschlossen, Stornierung nicht möglich" }, damit die Partner-App dem Nutzer eine konkrete Rückmeldung anzeigen kann.