Diskussion:REST-API und Websocket-Events von ARSnova

Aus THM-Wiki
Version vom 13. November 2013, 19:44 Uhr von Dgrh99 (Diskussion | Beiträge) (hat „Diskussion:RESTful Web-API für ARSnova2“ nach „Diskussion:REST-API und Websocket-Events von ARSnova“ verschoben)
(Unterschied) ← Nächstältere Version | Aktuelle Version (Unterschied) | Nächstjüngere Version → (Unterschied)
Wechseln zu: Navigation, Suche

Änderungsvorschläge und Überlegungen

URL-Pfade

  • Kleinscheibung und camelCase nicht mischen
  • doppelte Pfade für eine Ressource streichen oder konsequent für alle Pfade, bei denen es sinnvoll wäre, umsetzen
  • Ist die Benutzerauthentifizierung über die RESTful-API brauchbar umsetzbar?
  • Gastlogin problemlos umsetzbar, da vom ARSnova-Server eigenständig behandelt
  • Login mit Zugangsdaten problematisch, da andere Server einbezogen werden
  • Logout ist bereits RESTful
  • Authentifizierungs-URLs unter /auth/... unterbringen?
  • Einzahl und Mehrzahl nicht mischen (z.B. question und questions)
  • Feedback-URLs unter /session/{session}/feedback/... unterbringen
  • Unterschied von Question, Interposed und Skillquestion klar definieren
  • umbenennen; z.B. in .../question/bylecturer/... und .../question/byaudiance/...
  • Socket-IO: alle URLs mit /socket/ beginnen lassen
  • /authorize umbenennen, z.B. /socket/assign
  • Canteen: Requests vereinheitlichen
  • z.B. [GET|POST] /canteen/menu/vote und GET /canteen/menu/vote/results
  • Sollte der Session-Key-Teil aus URLs, die nicht direkt mit der Sessionverwaltung zusammenhängen, gestrichen werden?
  • Bei Abfragen von Daten, die zu einer Session gehören, kann der Key vom Server ermittelt werden
  • Bei Erstellung von Daten, könnte (und wird bereits jetzt) der Key als Teil des HTTP-Bodys gesendet werden
  • Vorteil: URLs übersichtlicher

HTTP-Status-Codes

  • immer 404, wenn die Ressource zu einer ID (question, answer, session) nicht existiert
  • nicht 404 sondern 204, wenn URL korrekt, aber noch keine Daten gespeichert worden sind
  • evtl. bessere Lösung: 200 und leeres JS-Array/-Objekt [] bzw. {} zurückgeben
  • könnte die Verarbeitung des Rückgabewertes vereinfachen
  • Verwendung von PUT für die Erstellung und Bearbeitung von Ressourcen, deren Abfrage-URL mit der fürs Bearbeiten verwendeten übereinstimmt
  • für andere Daten weiterhin POST

Fehlerbehandlung

  • Zum Teil werden (unerwartete) Exceptions abgefangen (in Service- oder Datenbankcode) und geloggt aber keine Exception an den Controller weitergereicht.
  • Es könnte passieren das 200 oder eine andere Erfolgsmeldung an den Client gesendet wird, obwohl ein Fehler aufgetreten ist.
  • 5xx sollte im Fehlerfall gesendet werden.


Kommentare zu Änderungsvorschlägen

URL-Pfade

Kleinscheibung und camelCase nicht mischen

Volle zustimmung. Auch wenn RFC 2396 zwischen Groß- und Kleinschreibung unterscheidet und daher ein Mischen möglich macht, so sollten wir, da in unserem Fall eine Unterscheidung absolut nicht notwendig ist, auf eine generiche Kleinschreibung zurückgreifen.

Ist die Benutzerauthentifizierung über die RESTful-API brauchbar umsetzbar?

Durch Verwendung von HTTP-Basic-Authentifizierung ließe sich eine brauchbare Implementierung schaffen. Allerdings ausschließlich für Verfahren, welche nicht eine Interaktion mit anderen Diensten und Redirects benötigen. Hierbei fallen also Google und Facebook mit OAuth, sowie CAS aus.

Dies betrifft allerdings nur die erste Authentifizierung gegenüber ARSnova, die sonstige Interaktion mit der API erfolgt über eine zuvor durchgeführte Authentifizierung und einem Session-Cookie. Durch diese Übermittlung der Session-ID wird eine brauchbare Benutzerauthentifizierung auf Shared-Secret-Basis durchgeführt.

Authentifizierungs-URLs unter /auth/... unterbringen?

Die Semantik der Anwendung entspricht folgender Vorgehensweise:

  • Unter Kenntnis des Session-Keys (Definiert als 8-stellige numerischer Schlüssel für eine Session) hat jeder Benutzer Zugriff auf eine Session.
  • Für ARSnova gilt das Betreten einer Session bereits als Authentifizierung.

Mein Vorschlag ist es daher, lediglich eine personenbezogene Authentifizierung unter /auth/... abzuelegen, da ansonsten der sematische Zusammenhang zwischen dem Betreten einer Session unter Angabe des Session-Keys und der Authentifizierung für eine Session verloren geht.

Einzahl und Mehrzahl nicht mischen (z.B. question und questions)

Hier stimme ich voll zu. Aus sematischer Sicht sollte bisher, so wurde es auf mehreren JourFixes genannt, Singular und Plural getrennt werden. Aus technischer Sicht spricht jedoch in meinen Augen nichts für eine solche Trennung. Es sollte klar sein, dass, wenn nicht genau eine spezielle Entität adressiert wird, alle Entitäten auf der Hirarchieebene gemeint sind.

Sollte der Session-Key-Teil aus URLs, die nicht direkt mit der Sessionverwaltung zusammenhängen, gestrichen werden?

Meiner Meinung nach entspricht das Datenmodell von ARSnova einer Hirarchie. Grundlegend gibt es Sessions, diese können Fragen, Zwischenfragen, Statistiken etc. beinhalten. Jedes dieser Elemente ist einer Session zugehörig. Dieses Datenmodell soll auch durch den sematischen Aufbau der URI verdeutlicht werden. So wird klar, dass mit /session/12345678/question/4711 die Frage 4711 der Session 12345678 gemeint ist. Ähnliches gilt auch für Statistiken etc. Da jedoch auch der zugehörige Session-Key Teil des Request-Bodys ist, könnte der Gedanke aufkommen, dies seien zu vermeidende Redundanzen. Werden die entsprechenden Teile aus der URI entfernt, ist jedoch der semantische Aufbau der URIs an sich nicht mehr gegeben. Dies ist meiner Meinung nach ein Nachteil.

Wird dieser Vorschlag ins Extreme getrieben, kommen wir an einen Punkt, an dem alle schreibenden Requests genau einer URI zugeordnet sind, welche anhand des Aufbaus des Request-Bodys entscheidet, was genau mit dieser Anfrage geschen soll. Dies ist nicht sehr RESTful. Ein POST-Request sollte immer an das "Verzeichnis" gerichtet werden, in dem das Dokument angelegt werden soll, ein PUT-Request sollte immer das Ziel direkt adressieren.

HTTP-Status-Codes

nicht 404 sondern 204, wenn URL korrekt, aber noch keine Daten gespeichert worden sind ...

Für welchen Fall sollte so etwas zutreffen? Ich kann mir hier nur vorstellen, dass damit zum Beispiel URIs wie /session/12345678/question/ gemeint sind, und noch keine Fragen für diese Session vorhanden sind. Alle anderen Fälle adressieren entweder genau ein Dokument (und geben 404 zurück) oder liefern einen Wert zurück.

Für genau diesen Fall, um das Zählen von Einträgen zu nennen, sollten wir genau abwägen, ob es sinnvoll ist eine URI für solche Anfragen zu definieren. Natürlich lassen sich so eins-zu-eins Methodenaufrufe abbilden, die im Client benötigt werden, allerdings wird oft eine solche Abfrage zeitgleich mit der Abfrage aller entsprechenden Dokumente erfolgen. Für die Statistik wurden solche Mehrfachabfragen von mir entfernt und dadurch 3 der vorher durchgeführten 4 Abfragen eingespart. Ist es nicht intelligenter Daten, welche ständig abgefragt werden soweit zusammenzufassen, dass eher eine etwas größere Antwort erwartet werden kann, als dass mehrere kleine Anfragen durchgeführt werden? Das Zählen von Elementen in einem Array ist in JavaScript kein Problem und vor einer solchen Codeänderung sollten wir keine Angst haben, auch wenn wir dann etwas an ARSnova 1 ändern müssen. Nichtbenötigte Daten können auch clientseitig vorgehalten werden, damit bei einem "Touch" kein Request erfolgen muss, da die benötigten Daten bereits vorhanden sind. Die Datenmänge ist hier sicher nicht entscheident, denn es handelt sich nicht um kB-große Grafik- oder CSS-Dateien.

Verwendung von PUT für die Erstellung und Bearbeitung von Ressourcen, deren Abfrage-URL mit der fürs Bearbeiten verwendeten übereinstimmt

Generell sollten alle bereits vorhandenen Dokumente mit einem PUT ersetzt werden. Ist die volle URI eines Dokuments auch bereits bekannt, muss nicht erst ein POST erfolgen, in dessem Request-Body zudem alle Daten vorhanden sind, um eine URI zu bilden. Hier kann und sollte sofort ein PUT-Request durchgeführt werden.

Weitere Anmerkungen

Die URIs /statistics/sessioncount und /activeusercount sind wohl obsolet, die entsprechenden Daten sind unter /statistics wohl besser aufgehoben. Handelt es sich um Session-Statistiken, ich denke da an die Anzahl der Fragen, Feedback, Benutzer in der Session, ist eine URI /session/12345678/statistics das Mittel der Wahl um auf einen Schlag alle Informationen abzurufen. Dadurch werden zahlreiche andere kleine Requests obsolet und die Anzahl der Requests kann gesenkt werden. Allerdings müsste dazu der Code angefasst werden ...