Auf dieser Seite gibt es eine Liste aller Requests, die ein Client an den Server senden kann. Anders gesagt: Eine Beschreibung der API des Servers.

Grundlegende Informationen

Requests und Begriffe

Ein Request besteht aus mehreren Teilen:

• Method: Die HTTP-Request Methode (GET, POST, PUT, ...)
• Host: Name des Servers
• URL-Path: Das was im Browser nach dem Hostnamen steht. Mehrere Blöcke durch / getrennt.
• Query-String: Steht im Browser nach dem Pfad hinter einem ?. Es sind mehrere key=value Paare, die durch & getrennt sind. Einfache Daten können hier gut übergeben werden.
• Request-Body: Der eigentliche Körper des Requests kann diverse Daten enthalten. Oft sind es auch wieder mehrere key=value Paare, wie die, die bei einem HTML Formular erzeugt werden. Was für Daten im Körper erwartet werden können, gibt der "content-type" im Header an. Dateiupload wird auch über den Body geregelt. Hierbei gibt es aber kein Key-Value Paar, sondern der komplette Body besteht einfach aus der Datei.

Antworten

Der Server antwortet immer mit dem HTTP-Code 200 OK und einem JSON payload, wenn kein Fehler aufgetreten ist. Im Falle eines Fehlers wird ein HTTP-Code != 200 zurück gegeben und eine Antwort im JSON Format, die eine kurze Fehlerbeschreibung enthällt, sowie arbiträre andere Daten, die den Fehler eventuell näher beschreiben. Beide Arten von JSON Antworten enthalten immer die Felder "timestamp" und "query-duration".

Unterschiedliche API Versionen

Für Breaking Changes in der API brauchen wir ein Versionen System. Dazu ist der erste Teil des Request-Pfades immer '/v*/' wobei * für eine Nummer steht. Derzeit haben wir natürlich nur eine API, daher bestehen alle Requests aus: ${server}/v1/${API-Path}

Der API-Path ist im Weiteren beschrieben.

Version /v1

/canteen

Informationen zu Mensen

GET /canteen/nearest

Status: Implemented, online.

Die Mensen, die der übergebenen Position am nächsten sind. Dabei werden maximal X Ergebnisse zurückgeliefert, wobei X derzeit vom Server bestimmt wird. Die Position wird per HTTP-Query-string über die Variablen "lat" und "lng" übergeben, also z.B. canteen/nearest?lat=52.284364&lng=8.022781

GET /canteen/id/:id

Status: Implemented, offline

Liefert genau eine Mensa mit der ID id. Optional kann auch die Distanz zur aktuellen Position auf dem Server berechnet werden (nicht auf dem Client berechnen!). Dazu müssen einfach nur die Werte für lat und lng wie bei /nearest übergeben werden. Beispiel Request: /canteen/id/3?lat=52.152&lng=7.1337. Wenn lat und lng nicht (oder falsch) übergeben werden, ist "distance"=-1.

/user

Die Nutzer des Systems.

GET /user/:id

Status: Implemented, offline

Liefert genau einen User mit der id id zurück (oder einen Fehler, wenn die ID nicht existiert). Man kann im Querystring mit thumbnail=true angeben, dass man den Thumbnail des Nutzeravatars im Base64-Format mitgeliefert bekommen möchte. Dieser vergrößert die Antwort um ca. 2 KB. Wenn diese Option nicht angegeben wurde, ist der Wert von thumbnail in der Antwort ein leerer String.

PUT /user/:id/avatar

Status: Implemented, offline

Über diesen Request kann man den Avatar eines Users ändern. Der komplette Inhalt der png oder jpeg Datei wird per Request-Body/Post-Daten übersendet. Zurück kommt ein Fehler, wenn etwas nicht geklappt hat oder ein simples "Success".