Proxer API/v1

Aus Proxer.Me - Wiki
Wechseln zu: Navigation, Suche

Dies ist die erste Auflage der neuen API, Version Nummer 1. Sollten jemals größere Änderungen am grundlegenden System der API gemacht werden, so wird es eine neue Version geben. Alle Änderungen jedoch, die innerhalb dieser Version erledigt werden können bleiben auch innerhalb der Version.

Zugriff

API-Keys

Im Gegensatz zur alten API ist der Zugriff auf die Schnittstellen der neuen API nicht mehr für jeden möglich. Stattdessen muss jede Anwendung einen für die Anwendung spezifischen "API-Key" mit jeder Anfrage mitsenden, mit dessen Hilfe entschieden wird, ob diese Anwendung berechtigt ist, auf die gewünschte Schnittstelle zuzugreifen. Ist sie das nicht, so wird eine Fehlermeldung zurückgegeben. (Code 1004, näheres unter "Fehlerbehandlung").

API-Keys müssen bei jeder Anfrage als POST-Parameter mit versendet werden. Der Parameter trägt den Namen "api_key". Alternativ kann der Key als Header übergeben werden. Der zu verwendende Header ist dabei 'proxer-api-key'.

Dabei hat der POST-Key mehr Priorität als der Header-Key (falls beide versendet werden)

Um einen API-Key zu erhalten, sollte man sich per PN entweder an genesis oder Nihongasuki wenden.

Das Weitergeben von API-Keys ist strengstens untersagt! Ein mutwilliger Verstoß gegen diese Regelung wird entsprechende Sanktionen nach sich ziehen, beispielsweise der Entzug der API-Keys der beteiligten Entwickler auf Dauer!

Login

Zudem gibt es einige Schnittstellen, die einen eingeloggten User erfordern, um genutzt werden zu können. Da es auf einigen System bzw. in einigen Programmiersprachen Probleme mit dem Standardmäßigen Cookie-System Joomlas gibt, wurde eine Fallbackmethode für diese System und Sprachen eingerichtet: Bei jedem (erfolgreichen) Aufruf der Login-Schnittstelle wird ein für die Anwendung und den eingeloggten User spezifisches Login-Token erstellt, dass über den Parameter "token" im Datenfeld zurückgegeben wird (näheres unter "Schnittstellen"). Dieses Token ist ein 255 Zeichen langer String. Sendet man es bei einer Anfrage als POST-Paramter mit, so wird der User, dem das Token zugeordnet ist, vor dem eigentlichen Aufruf der Schnittstelle eingeloggt. Dies funktioniert jedoch nur, wenn nicht bereits ein User durch das Cookie-System als eingeloggt gilt (in solch einem Fall wird das Token einfach ignoriert und der bereits eingeloggte User verwendet). Diese Methode erzeugt einen zusätzlichen Overhead für die Schnittstelle (verlängert also die Antwortzeit des Servers), weswegen man es sich gut überlegen sollte, ob man sie wirklich verwenden möchte. Sendet man kein Token, so gibt es auch keinen Overhead.

Das Token kann entweder per POST gesendet werden als "api_token"

Oder aber man sendet es als header mit, unter dem Namen "proxer-api-token"

Dabei sind Token nicht unendlich lange gültig. Damit ein Token als gültig anerkannt wird, müssen folgende Bedingungen erfüllt sein:

  • Das Token muss innerhalb der letzten 7 Tage erstellt oder verwendet worden sein UND eine der Folgenden Bedinungen muss erfüllt sein:
    • Das Token wurde nicht länger als 30 Tage zuvor erstellt ODER
    • Das Token wurde nicht länger als 1 Stunde zuvor verwendet

Dadurch lässt sich das Token verwenden, um die Speicherung von Userdaten zu vermeiden, zum Beispiel:

  • Man loggt einen User ein, indem dieser seine Daten an die App gibt und diese die Userdaten direkt an die Schnittstelle weitergibt, ohne sie zwischenzuspeichern.
  • Die App speichert das Login-Token, dass die Schnittstelle zurückgibt, verwendet allerdings trotzdem das cookie-Login System (natürlich kann sie auch das token-System verwenden)
  • Wann immer eine "User nicht eingeloggt" Fehlermeldung (egal wo) kommt (oder bei jedem App-Start etc.), wird eine beliebige Schnittstelle mit dem Token aufgerufen, z.B. die Login-Schnittstelle.
  • Dadurch wird der User wieder eingeloggt, ohne dass dessen Daten lokal gespeichert sein müssen
  • Dies lässt sich bis zu einen Monat lang wiederholen (wenn der User mindestens einmal alle 7 Tage die App verwendet), dann muss der User seine Daten erneut eingeben

Die Ein-Stunden Regel dient dazu, zu verhindern, dass für eine App (die nur das Token verwendet, also keine Cookies) mitten in der Benutzung das Token ungültig wird. Die Verwendung eines ungültigen Tokens erzeugt eine Fehlermeldung (Code 1005).

WICHTIG: Durch ein Aufrufen der Logout-Schnittstelle wird das entsprechende Token gelöscht (Wenn es überhaupt einen User gab, der ausgeloggt werden konnte).

Schnittstellen

Klassen

Grundsätzlich ist jede Schnittstelle der neuen API einer "Klasse" zugeordnet. Zudem hat jede Schnittstelle einen eigenen "Zugriffslevel", der 0 oder höher ist. Diese beiden Werte sind hauptsächlich wichtig für die Bestimmung der Berechtigungen eines API-Keys, da diese pro Klasse und Maximallevel vergeben werden (Ein Key mit Berechtigungen für Level 1 kann also auch auf Level 0 zugreifen). Für die Level gilt generell: Getter haben Level 0, Setter Level 1. Ausnahmen und Sonderfälle (Level 2 und höher) sind in der Dokumentation der Klasse gekennzeichnet.

Folgende Klassen sind momentan vorhanden:

Anfrage

Jede Schnittstelle der neuen API hat die selbe Grundstruktur. Sie kann über einen Link der Form "proxer.me/api/<api_version>/<api_class>/<api_function>" erreicht werden, wobei gilt:

  • api_version: Die Versionsnummer der API, momentan nur v1. In Zukunft wird es vielleicht weitere Versionen geben.
  • api_class: Die Klasse der aufzurufenden Schnittstelle
  • api_function: Die Schnittstelle selbst

Jeder weitere geforderte Parameter (in der Dokumentation zu finden) muss mit Namen entweder als GET oder POST Parameter versendet werden. Manche Schnittstellen lassen nur POST-Zugriffe zu.

Ausgabe

Jede Schnittstelle gibt ihre Daten in der selben Form aus, und zwar als ein JSON-codiertes Objekt mit folgenden Paramtern:

  • error: Dieser Parameter enthält entweder 0 oder 1. 0 Bedeutet, dass kein Fehler aufgetreten ist, 1 zeigt einen Fehler an. Generell kann davon ausgegangen werden, dass bei einem error-Wert von 1 der eigentliche Zweck der Schnittstelle nicht erfüllt wurde (diese also u.U. erneut aufgerufen werden muss)
  • message: Dieser Parameter enthält einen String, der das Ergebnis der Abfrage in Klartext enthält (Also entweder eine Fehlermeldung oder eine Erfolgsmeldung). Dieser ist v.a. für die Ausgabe an den User geeignet, für den Entwickler ist er wohl weniger interessant.
  • data: Dieser Parameter enthält die von der Schnittstelle zurückgelieferten Daten, wenn der Zugriff erfolgreich war (error == 0) und die Schnittstelle den Zweck hat, Daten zu liefern. Der Inhalt hat Abhängig von der Schnittstelle verschiedene Formate, das häufigste ist jedoch ein Array von Objekten, die alle die gleichen Parameter haben (spezifiziert in der Dokumentation).
  • code: Sollte der Zugriff auf die Schnittstelle fehlschlagen (error == 1), so wird ein Integer als Fehler-Code ausgegeben. Näheres dazu unter "Fehlerbehandlung"

Fehlerbehandlung

Im Falle eines Fehlers wird zur besseren automatischen Verarbeitung ein Fehlercode ausgegeben. Diese Codes sind eindeutig und ermöglichen eine sehr spezifische Behandlung des Fehlerfalls innerhalb der Anwendung. Theoretisch kann in den meisten Fällen aber auch einfach der "message" Parameter der Antwort an den User ausgegeben werden und auf dessen Reaktion gewartet werden (v.a. bei Fehlern betreffend falscher Eingaben des Users).

Jeder Code ist ein 4-stelliges Integer.

Kategorien

Alle Fehler sind grob in drei Kategorien Unterteilt:

  • Fatale Fehler: Dies sind Fehler, die die Funktion der Schnittstelle komplett unterbinden. Das trifft hauptsächlich auf vom Entwickler verursachte Fehler zu, wie etwa die Angabe eines Fehlerhaften API-Keys oder der Versuch, auf eine nicht autorisierte Schnittstelle zuzugreifen. Alle Codes dieser Kategorie haben als erste Ziffer eine 1.
  • Serverbedingte Fehler: Dies sind Fehler, die aufgrund eines Fehlers innerhalb des Servers entstanden sind, wie z.B. ein Verbindungsfehler zum Datenbank Server, oder aber auch die Blockierung der IP des Nutzers. Gegen diese Fehler kann man kaum mehr tun als es einfach nochmal zu versuchen. Alle Codes dieser Kategorie haben als erste Ziffer eine 2.
  • Eingabefehler & sonstige Fehler : Dies sind Fehler, die aufgrund einer falschen Eingabe durch den User oder fehlender Paramter verursacht wurden. Alle Codes dieser Kategorie haben als erste Ziffer eine Zahl größer 2.

Hinweis: Serverbedingte Fehlercodes beinhalten nicht die Behandlung von Totalabstürzen (HTTP Error 500) oder ähnlichem. Diese Art Fehler müssen vom Programm selbst erkannt werden (schließlich kann der Server bei einem Totalabsturz ja keinen Code mehr senden).

Codes

Fehler, die bei einer speziellen Schnittstelle auftreten können, sind in deren Dokumentation festgehalten. Fehler die bei jeder Schnittstelle auftreten können werden jedoch nicht explizit erwähnt, sondern sind stattdessen unter http://proxer.me/wiki/Proxer_API/v1/Codes zu finden. Dabei sind alle Fehler der Kategorie 1 und alle nicht spezifischen Fehler der Kategorie 2 als allgemein zu verstehen.

Changelog

Ein Changelog für die API ist hier zu finden: Proxer API/v1/Changelog