Grundlagen des Webs - Praxis/Workshop Teil

Dokumentation

REST API - Siehe REST Modellierung

Authentifikation

Aktuell benötigt der Service keine Authentifikation und jeder Nutzer kann auf alle Funktionen zugreifen.
Siehe Anwendungslogik - Zukünftige/Mögliche Verbesserungen

HTTP Requests / HTTP Anfragen

Alle API-Anfragen werden über einfache HTTP-Requests getätigt.
Abhängig von der durchgeführten Aktion sind folgende Methoden möglich:

• POST Erstellt eine Ressource
• GET Liefert eine Ressource oder eine Liste von Ressourcen
• PATCH Aktualisiert eine Ressource
• DELETE Löscht eine Ressource

Bei POST, PATCH und DELETE Requests muss die Anfrage im body einen JSON-Payload mit bestimmten Informationen enthalten. Zusätzlich kann die URL bei einigen Anfrage über einen Pfad- oder Query-String verfügen. All dies wird in den folgenden Abschnitten erläutert.

HTTP Responses / HTTP Antworten

Jeder Response enthält ein status und (wenn die Anfrage erfolgreich ist) ein result Objekt. result ist ein einfaches Objekt bei Einzelsatzanfragen und ein Array bei Listenanfragen. Das status Objekt enthält den HTTP status_code und den status_text. Wenn bei der Anfrage ein Fehler aufgetreten ist und kein result Objekt in der Antwort enthalten ist, gibt es stattdessen ein error Objekt mit näheren Informationen zum Fehler.
Die Antwort auf einen GET-Request an /events könnte zum Beispiel so aussehen:

{
  "status": {
    "status_code": 200,
    "status_text": "OK"
  },
  "result": [
    {
      "_id": "5e1c837fbdadea02805e1298",
      "name": "Gryphon pres. Weska [Drumcode], Klines, Sven Sossong, uvm",
      "location": "Mauerpfeiffer Lebacher Str 1-7a, 66113 Saarbrücken",
      "date": 18012019,
      "topic": "TECHNOOO"
    }
  ]
}

HTTP Response Codes / HTTP Antwort Codes ( Status Codes )

Jeder Response wird mit einem der folgenden HTTP Status Codes beantwortet:

• 200 OK Die Anfrage war erfolgreich
• 201 Created Die Anfrage war erfolgreich und es wurde eine neue Ressource erstellt
• 400 Bad Request Die Anfrage war ungültig (Parameter, Daten, etc.)
• 404 Not Found Es wurde versucht auf eine Ressource zuzugreifen, die nicht existiert
• 500 Internal Server Error Beim Verarbeiten der Anfrage ist ein Error aufgetreten

Request Modifiers / Anforderungsmodifikatoren

Bestimmte Anfrage können oder müssen mit zusätzlichen Informationen spezifiziert werden.
Bei GET und PATCH Requests wird eine Ressource über einen Pfad-Parameter (in Form einer ID) identifiziert.
Bei der Anfrage eines bestimmten Sets können mit Hilfe des Query-Parameters orderBy die Tracks sortiert werden.

Ressources / Ressourcen

Für eine Übersicht und die Definition/Beschreibung von Ressourcen siehe Anwendungslogik.

Events

• GET Liefert eine Liste aller Events.
• GET Liefert Informationen zu einen bestimmten Event.
• POST Fügt ein neues Event hinzu.
• PATCH Aktualisiert Informationen eines bestimmten Events.
• DELETE Löscht ein bestimmtes Event.

Sets

• GET Liefert eine Liste aller Sets.
• GET Liefert Informationen zu einen bestimmten Set.
• POST Fügt ein neues Set hinzu.
• PATCH Aktualisiert Informationen eines bestimmten Sets.
• DELETE Löscht ein bestimmtes Set.

Requests

• GET Liefert eine Liste aller Requests.
• GET Liefert Informationen zu einen bestimmten Request.
• POST Fügt einen neuen Request hinzu.
• DELETE Löscht einen bestimmten Request.

Website / Client Demo

Usecase

Für die einfache und übersichtliche Nutzung der Rest API wurde eine Website erstellt, welche die verschiedenen Anfragen über Formulare und HTTP Requests ermöglicht und die Antworten verarbeitet, sodass sie für Menschen lesbar/ersichtlich sind. Es wurde besonders auf Einfachheit und Verständlichkeit für den durchschnittlichen Benutzer geachtet.

Navigation

Mögliche Operationen sind:

• Event erstellen
• Set erstellen
• Request/Song-Vorschlag erstellen
• Suchen
• Löschen

Operationen

Event erstellen

Um ein Event zu erstellen benötigt man einen Namen, ein Thema, ein Datum (Format: ttmmyyyy) und eine Location.

Set erstellen

Um ein Set zu erstellen benötigt man eine EventID, um zu bestimmen zu welchem Event das Set gehört, einen Namen und eine Kurzbeschreibung (Beispiel: Genre, gewünschte Künstler, ...).

Request/Song-Vorschlag erstellen

Um einen Song-Vorschlag zu erstellen benötigt man eine SetID, um den jeweiligen Track einem Set zuweisen zu können, sowie eine Spotify TrackID. Die SetID kann bspw. über die Suche ermittelt, oder durch externe Quellen erhalten werden. Die TrackID kann direkt aus Spotify entnommen werden. Mögliche Variationen sind dabei die Track-URL, sowie die eindeutige Track-URI.

Suchen

Über einen Radio-Button (Auswahlbutton) kann der Typ der gesuchten Ressource und optional auch die gewünschte Filterung/Sortierung für Requests innerhalb eines Sets bestimmt werden. Für Einzelsatzanfragen kann außerdem eine ID angegeben werden. Die Filterung/Sortierung für Requests innerhalb eines Sets ist nur bei einer Einzelsatzanfrage möglich.

Löschen

Über einen Radio-Button (Auswahlbutton) kann der Typ der zu löschenden Ressource bestimmt und im Anschluss die zugehörige ID angegeben werden.

Ausgabe

Das Ausgabefenster gibt dem Nutzer eine leichte verständliche Rückmeldung darüber, ob eine POST oder DELETE Request erfolgreich war oder ob dabei ein Fehler aufgetreten ist. Bei GET Requests erfolgt die Ausgabe der Antwort von der API in Form von Tabellen.