Modellierung der Schnittstelle - tvoss-busch/GDW_ws2021_Remberg_Russmann_Voss-Busch_repository GitHub Wiki
URI der Ressourcen
Die Ressource in unserem Szenario hat die URI "https://wir-suchen-dein-fahrer.com/". Diese ist über eine SSL/TLS verschlüsselte HTTP-Verbindung erreichbar. Zur besseren Verwendung (sowohl von Entwicklern, als auch von Privatanwendern) haben wir uns entschieden die Repräsentation dieser URI wahlweise in JSON, PDF oder XML anzubieten.
Primärressourcen
Zu den Primärressourcen zählen bei uns die Ressourcen "/users", "/drivers", "../offers", "../bookings" und "/maps". Unter Listenressourcen fallen in unserem Szenario etwa "/users", "/drivers", "../offers", "../bookings", da sie jeweils eine Menge von Instanzen (etwa User Accounts) repräsentieren. Alle Path-Parameter befinden sich im URI-Bezeichner nach ".com" und sind durch einen Querstrich "/" von einander getrennt. Sie dienen dazu die Ressource vollständig zu identifizieren. Es handelt sich dabei um die folgenden Path-Parameter, die weiter unten in der Tabelle zu "Semantik der Verben" aufgelistet sind.
Query-Parameter
Die optionalen Query-Parameter, die als zusätzliche Anfrage bei einer Anfrage an den Server mitgeschickt werden, können sich ebenfalls positiv auf die Berechnungszeit der Anfragen auswirken. Sie finden sich im Bezeichner der URI charakteristisch nach einem Fragezeichen "?", das den Path-Teil der URL abschließt. Die Query-Parameter sollten auf jeden Fall ergänzt werden, da sie nützlich sind im Zusammenhang mit Tokens und der Zugriffsauthorisierung bei bestimmten zugriffssensitiven Ressourcen (etwa Account Informationen).
Semantik der Verben
| Ressource | GET | POST | PUT | DELETE |
|---|---|---|---|---|
| /users | Zeigt die Liste aller Nutzers an (Code 200) | Methode nicht erlaubt (Code 405) | Methode nicht erlaubt (Code 405) | Methode nicht erlaubt (Code 405) |
| /users/{id} | Zeigt die ID eines Nutzers an (Code 200) | Legt einen neuen Nutzer an, falls ID nicht vorhanden (Code 201). Ansonsten keine Änderung (Code 405). | Legt einen neuen Nutzer an, falls ID nicht vorhanden (Code 201). Ansonsten Code 405 | Löscht Nutzer (Code 204 bzw. 200). |
| /users/{id}/bookings | Zeigt die Liste aller gebuchten Mitfahrangebote an (Code 200) | Methode nicht erlaubt (Code 405) | Methode nicht erlaubt (Code 405) | Methode nicht erlaubt (Code 405) |
| /users/{id}/bookings/{id} | Zeigt eine spezifisches Buchung eines spezifischen Nutzers an (Code 200) | Legt eine neue Buchung an, falls ID nicht vorhanden (Code 201). Ansonsten keine Änderung (Code 405). | Legt eine neue Buchung an, falls ID nicht vorhanden (Code 201). Ansonsten wird Buchung geupdated (Code 200) | Buchung aus Liste löschen (Code 204 bzw. 200) |
| /users/{id}/account-information | Zeigt die Nutzer-Informationen eines spezifischen Nutzers an (Code 200) | Legt neue Nutzer-Informationen an, falls ID nicht vorhanden (Code 201). Ansonsten keine Änderung (Code 405). | Legt neue Nutzer-Informationen an, falls ID nicht vorhanden (Code 201). Ansonsten werden Nutzer-Informationen geupdated (Code 200) | Nutzer-Informationen werden gelöscht (Code 204 bzw. 200) |
| /drivers | Zeigt eine nach Bewertungen sortierte Liste mit Fahrern an (Code 200) | Methode nicht erlaubt (Code 405) | Methode nicht erlaubt (Code 405) | Methode nicht erlaubt (Code 405) |
| /drivers/{id} | Zeigt die ID eines Fahrers an (Code 200) | Legt einen neuen Fahrer an, falls ID nicht vorhanden (Code 201). Ansonsten keine Änderung (Code 405). | Legt einen neuen Fahrer an, falls ID nicht vorhanden (Code 201). Ansonsten werden Fahrer-Informationen geupdated (Code 200) | Löscht Fahrer (Code 204 bzw. 200). |
| /drivers/{id}/offers | Zeigt eine Liste mit Mitfahrangeboten eines spezifischen Fahrers an (Code 200) | Methode nicht erlaubt (Code 405) | Methode nicht erlaubt (Code 405) | Methode nicht erlaubt (Code 405) |
| /drivers/{id}/offers/{id} | Zeigt ein spezifisches Mitfahrangebot eines spezifischen Fahrers an (Code 200) | Legt ein neues Mitfahrangebot an, falls ID nicht vorhanden (Code 201). Ansonsten keine Änderung (Code 405). | Legt ein neues Mitfahrangebot an, falls ID nicht vorhanden (Code 201). Ansonsten wird Mitfahrangebot geupdated (Code 200) | Mitfahrangebot aus Liste löschen (Code 204 bzw. 200) |
| /drivers/{id}/account-information | Zeigt Account-Informationen eines spezifischen Fahrers an (Code 200) | Legt neue Fahrer-Informationen an, falls ID nicht vorhanden (Code 201). Ansonsten keine Änderung (Code 405). | Legt einen neue Fahrer-Informationen an, falls ID nicht vorhanden (Code 201). Ansonsten werden Fahrer-Informationen geupdated (Code 200) | Fahrer-Informationen gelöscht (Code 204 bzw. 200) |
| /drivers/offers | Zeigt eine Liste mit aktuellen Mitfahrangeboten an (Code 200) | Methode nicht erlaubt (Code 405) | Methode nicht erlaubt (Code 405) | Methode nicht erlaubt (Code 405) |
| /drivers/offers/destinations | Zeigt eine Liste mit beliebten Reisezielen an (Code 200) | Methode nicht erlaubt (Code 405) | Methode nicht erlaubt (Code 405) | Methode nicht erlaubt (Code 405) |
| /drivers/offers/destinations/{id} | Zeigt eine Liste mit Mitfahr-/ Reiseangeboten an (Code 200) | Neue Route wird ausgewählt (Code 200) | Aktuelle Route wird geupdated (Code 200) | Löscht aktuelle Suche (Code 204 bzw. 200) |
| /maps | Zeigt die Map an (Code 200) | Methode nicht erlaubt (Code 405) | Methode nicht erlaubt (Code 405) | Methode nicht erlaubt (Code 405) |
| /maps/{user-id}/tracking | Zeigt die Route/ aktuelle Position des Nutzers an (Code 200) | Methode nicht erlaubt (Code 405) | Methode nicht erlaubt (Code 405) | Methode nicht erlaubt (Code 405) |
Im Falle von GET-Requests zu nicht existierenden Ressourcen sollte generell mit Code 404 reagiert werden.
TODO
Die essentiellen Ressourcen und Methoden/ Verben sind definiert worden. Im weiteren Vorgehen kann man darüber diskutieren ob im Rahmen unseres Projektes auch betriebswirtschaftliche Aspekte, wie z.B. Dinge wie Kostenbeteiligung, Vermittlungsgebühren oder Versicherungsleistungen Beachtung finden sollten.