[mitchatten]

Willkommen auf den iZ-smart.net Entwickler Seiten

Wir bieten seit Mai 2011 ein neues API an was detaillierte Informationen zu eurem Channel bzw. Nicknamen liefert.

Im wesentlichen bietet auch diese Version Chaninfo und Nickinfo wie ggf. von der modules.php bekannt. Jedoch nicht mehr in den altbekannten Plain-Text Formaten (wie zum Beispiel aus dem alten Chaninfo) sondern JSON (bzw. JSONP) - im Normalfall - in allen Modulen.

Als Datenlieferant bedient sich auch diese Version des API an SakIs (Swiss Army Knife IRC Services) – unserem selbst geschriebenen IRC Service, der sich in der Vergangenheit als extrem zuverlässiger und stabiler Datenlieferant bewährt hat.

Generelle API Informationen

Zu Channeln die die Modes +p, +s gesetzt haben, werden im API keine Informationen ausgegeben. Für Channel die Modes +k, +i, und +u gesetzt haben, werden keine Nutzer im Channel ausgegeben. Für Nutzer die Usermode +p gesetzt haben, werden ebenfalls keine Channel ausgegeben.

Die gezeigten Informationen belaufen sich nur auf Daten, die jeder Nutzer des Netzwerkes ebenfalls erlangen könnte, indem dem Channel gejoined wird (sofern möglich) bzw. ein /WHOIS auf einen Nutzer ausgeführt wird.

Wird der Topic eines Channel in einem der Module ausgegeben, ist dies immer inklusive aller Layoutelemente (Farben, Bold, Reverse, ...) zurückgegeben. Weiterverarbeiten lassen sich diese Daten mit beispielsweise JavaScript oder PHP.

Erste Beispiele - aktuell zu Chaninfo - sind auf GitHub bzw. GitHub Pages zu finden.

Mit diesen Seiten haben wir uns entschieden, das gesamte API offen zu legen und sämtliche Module zu dokumentieren - auch die, die für interne Zwecke entwickelt wurden.

Derzeit befindet sich das API v2 noch im Beta-Stadium. Änderungen (kleinere und größere) geben wir im Changelog bekannt. Änderungen an den URLs wird es nicht mehr geben.

bekannte Probleme

Schema

Alle Zugriffe laufen über HTTP GET, Basis-URL für Zugriffe ist:

http://api.relay-chat.de/2/

Module

Derzeit sind folgende Module verfügbar:

Parameter zu den Modulen werden in dieser Dokumentation mit einem Doppelpunkt (:) gekennzeichnet. Diese müssen im eigentlichen Request jedoch weggelassen werden. Aus einem Request an eine URL aus der Dokumentation (zum Beispiel http://api.relay-chat.de/2/nickinfo/:nick/:format/ wird am Ende http://api.relay-chat.de/2/nickinfo/hexa/json/).

URLs

Werden URLs innerhalb von Modulen angegeben sind diese immer relativ zur Basis-URL (siehe "Schema") angegeben.

Cache

Antworten liefern wir nach der ersten erfolgreichen Anforderung an eine URL aus einem internen Cache aus. Die Daten werden nur kurzzeitig zwischengespeichert (10 Sekunden).

Formate

Aktuell liefert das API v2 Daten in dem Format JSON (bzw. JSONP - siehe unten) aus.

Für einige Routen werden folgende weitere Formate unterstützt: YAML (als Format-Parameter in der URL wird hier yml bzw. yaml angegeben - Siehe Changelog Eintrag vom 28.03.2014). Für Nickinfo kann ebenfalls ein Bild (online/offline in je zwei Ausführungen) sowie eine vCard angefordert werden. Dokumentation hierzu findet sich jeweils auf den entsprechenden Unterseiten zu Nickinfo. Für Serverinfo steht ebenfalls die Ausgabe in Form eines Bildes zur Verfügung.

Authentifikation

Das API benötigt derzeit keinerlei Authentifizierung. Der Zugang zu den Informationen ist unbegrenzt möglich. Dies könnte sich in Zukunft ändern. Änderungen diesbezüglich werden im Changelog bekanntgegeben.

Rate-Limiting

Aktuell wird in keinem Modul Rate-Limiting (maximale Aufrufe pro Host und Minute) betrieben. Dies könnte sich in Zukunft ändern. Änderungen diesbezüglich werden im Changelog bekanntgegeben.

Common GET Parameter

Pretty Print (JSON)

Wenn der Parameter pretty auf true gesetzt ist, werden die Daten die zuvor komprimiert als JSON ausgegeben wurden in formatierter Form zurückgegeben um die Lesbarkeit zu erhöhen.

JSON Callbacks

Wenn der Parameter jsoncallback oder callback zu einem beliebigen Modul übergeben wird das per JSON antwortet, wird das JSON Objekt dementsprechend "eingepackt".

$ curl http://api.relay-chat.de/2/info/json?jsoncallback=foo
foo({
  "izsmart": {
    "ajax": false,
    "cache": false,
    "cache_hash": "90a883-0cac480a5698",
    "cache_online": true,
    "mobile": false,
    "runtime": 0.00306,
    "time": 1389296160,
    "version": "tiberius/2.0.60@production"
  }
});