Das hier ist die inoffizielle Dokumentation der XML Schnittstelle des mods.de Forums. Aktuell gibt es keine offizielle Dokumentation, deswegen versuche ich hier möglichst alle Funktionen zentral zu dokumentieren und möglichst ausführlich zu beschreiben. Wenn was fehlt oder hier was falsches stehen sollte, wäre es nett, einen Kommentar zu hinterlassen oder mir im Forum eine PM zu schreiben. Have Fun!
Wenn ihr auch eine Applikation gebastelt habt, die die API verwendet, könnt ihr einfach einen Kommentar schreiben und ich trags dann hier ein! ;)
Bei den ganzen vielen IDs die es hier gibt, wird einem ja ganz schwindelig. Daher hier eine Übersicht ;)
Abkürzung: | Name: | Beschreibung: |
---|---|---|
CID | Category-ID | Jedes Board gehört einer Kategorie an, jede Kategorie hat eine eigene CID |
BID | Board-ID | Jedes Board hat eine für alle Boards einzigartige ID |
TID | Thread-ID | Jeder Thread hat eine über alle Threads einzigartige ID |
PID | Posting-ID | Jedes Posting hat ebenso eine ID, die es komplett unabhängig von seinem Thread identifiziert |
UID | User-ID | Jeder Benutzer hat seine eigene UID. Die Profilseiten liegen z.B. unter http://my.mods.de/$UID |
Avatar-ID | Ebenso hat jede Instanz eines Avatars seine eigene ID | |
SID | Session-ID | Wird von PHP verwaltet, identifiziert die Session. Wird als Cookie vom Server gesendet und sollte nach dem Login bei jedem Aufruf wieder zum Server gesendet werden. |
Um sich einzuloggen reicht es die folgende Kombination an Parametern zu senden;> Man kann dann recht einfach nachschauen, ob es geklappt hat, wenn man die zurückgegebene Seite nach dem String "Fehler beim Einloggen" durchsucht. Im Erfolgsfall sollte man anschließend die benötigten Cookies setzen, dazu muss die für einen der iframes angegebene Adresse (http://forum.mods.de/SSO.php?...) geladen werden (momentan werden zwei iframes zurückgegeben, die identisch sind). Diese Cookies sollte man speichern und bei folgenden Aufrufen wieder an den Server schicken, benutzt man CURL kann das CURL für einen erledigen. Die Addresse des Logins lautet http://login.mods.de/
HTTP-Keyword | Name | Beschreibung |
---|---|---|
POST | login_username | Enthält den Benutzernamen |
POST | login_password | Enthält das Passwort (Klartext). |
POST | login_lifetime | Gibt an wie lange die Session gültig sein wird, in Sekunden.
Übliche Werte:
|
Zum Ausloggen reicht es einen einfachen Request an http://login.mods.de/logout/ abzusetzen. Jetzt kommt das aber: Es gibt einen Sicherungsmechanismus, man muss ein Sicherheitstoken übergeben. Bei Misserfolg kommt einfach eine leere Seite zurück, bei erfolgtem Ausloggen enthält die Seite den Text "Du hast dich ausgeloggt".
HTTP-Keyword | Name | Beschreibung |
---|---|---|
GET | UID | Die User-ID |
GET | a | Der Sicherheitstoken. Der Sicherheitstoken besteht aus 4 Buchstaben oder Zahlen und bleibt über eine ganze Session konstant. Es gibt keine Möglichkeit über eine schnicke XML-API sich das Sicherheitstoken ausgeben zu lassen. Am einfachsten kommt man also dran, indem man sich eine beliebige Seite vom Forum ausgeben lässt und den Logout-Link sucht und das Token extrahiert. |
Hier gehts um die möglichen Queries (Anfragen), die die eigentliche Funktionalität der XML API stellen. Alle Dateien der XML API liegen im Ordner http://forum.mods.de/bb/xml/, allerdings muss man hin und wieder (z.B. zum Anmelden) auch auf andere Pfade zugreifen). Parameter werden meistens per GET übergeben. Das ausgegebene XML hält sich an dieses XML-Schema.
Die board.php gibt Infos zu einem Board mit bekannter Board-ID (siehe dazu boards.php) inklusive einer Threadliste aus.
<?xml version="1.0" encoding="utf-8" ?> <board xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://forum.mods.de/bb/forum.xsd" current-user-id="1224901" id="43"> <name> <![CDATA[Webdesign & Coding]]> </name> <description> <![CDATA[Hello World!]]> </description> <number-of-threads value="4497"/> <number-of-replies value="220990"/> <in-category id="21"/> <threads with-stickies="1" with-globals="1" page="1" offset="0" count="30"> <thread id="189020"> <title> <![CDATA[Aktualisierte Forensatzung]]> </title> <subtitle> <![CDATA[vom 28.09.08]]> </subtitle> <number-of-replies value="0"/> <number-of-hits value="45239"/> <number-of-pages value="1"/> <flags> <is-closed value="1"/> <is-sticky value="1"/> <is-important value="1"/> <is-announcement value="1"/> <is-global value="1"/> </flags> <in-board id="14"/> <firstpost> <post> <user id="2822"> <![CDATA[Insaniac]]> </user> <date timestamp="1222589113">28.09.2008 10:05:13 </date> <in-thread id="189020"/> <in-board id="14"/> </post> </firstpost> </thread> </threads> </board>
current-user-id
User-ID
id
Board-ID
timestamp
-Attribut ist ein UNIX-Zeitstempel.
Inhalt ist ein vorformatiertes DatumHTTP-Keyword | Name | Beschreibung |
---|---|---|
GET | offset | Anzahl der am Anfang zu überspringenden Threads |
GET | with-globals | Wenn with-globals 1 ist (Standard ist auch 1), dann werden auch globale Threads ausgegeben, ansonsten nicht. |
GET | with-stickies | Wenn with-stickies 1 ist (Standard ist auch hier ebenfalls 1), dann werden Stickies ausgegeben, ansonsten... nicht ;) |
GET | BID | Die Board-ID zu der man Informationen abfragen möchte.
Wenn es kein Board mit dieser ID gibt, kommt ein <invalid-board/>zurück. |
Gibt eine Liste aller Foren zurück.
<?xml version="1.0" encoding="utf-8" ?> <categories xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://forum.mods.de/bb/forum.xsd" current-user-id="1224901" count="9"> <category id="6"> <name> <![CDATA[Allgemeines]]> </name> <description> <![CDATA[Seitenübergreifende Themen]]> </description> <boards count="4"> <board id="95"> <name> <![CDATA[3DSupply.de]]> </name> <description> <![CDATA[Alles rund um 3D Supply]]> </description> <number-of-threads value='451' /> <number-of-replies value='22040' /> <in-category id="6" /> <lastpost> <post> <user id="1241980"> <![CDATA[Chinakohl mit Reis]]> </user> <date timestamp="1311972627">29.07.2011 22:50:27 </date> <in-thread id="171342"> <![CDATA[3DSupply Produktfragen]]> </in-thread> <in-board id="95" /> </post> </lastpost> <moderators> <user id="2822"> <![CDATA[Insaniac]]> </user> </moderators> </board> </boards> </category> </categories>
Gibt alle vom angemeldeten Benutzer gesetzten Bookmarks zurück.
<?xml version="1.0" encoding="utf-8" ?> <bookmarks newposts="6" count="2"> <bookmark BMID="92071" newposts="6" PID="1242999267"> <thread TID="194906" closed="0" pages="325"> <![CDATA[Hardware-Kaufberatung]]> </thread> <board BID="10"> <![CDATA[Hardware & Netzwerk]]> </board> </bookmark> <bookmark BMID="95504" newposts="0" PID="1242999854"> <thread TID="140831" closed="0" pages="5525"> <![CDATA[Gehirnsalat]]> </thread> <board BID="43"> <![CDATA[Webdesign & Coding]]> </board> </bookmark> </bookmarks>Im Gegensatz zu den anderen Antworten auf API Queries, enthält das gelieferte XML Dokument für Bookmarks Whitespaces zur Formatierung für eine bessere Lesbarkeit durch Menschen. Einige XML Parser kommen damit nicht klar und erzeugen überflüssige Nodes, die als Text nur Whitespaces (Tabulatoren, (Windows-)Zeilenumbrüche) beinhalten. Dadurch kann zum Beispiel die Anzahl der Kinder des bookmarks Elements nicht mit der im Attribut count angegebenen Anzahl übereinstimmen; die Anzahl der tatsächlichen bookmark Kinder sollte aber mit dieser Angabe übereinstimmen.
Da sich der Ablauf und die Parameter sehr ähneln, verweise ich für weitere Informationen auf newreply.php und beschränke mich hier auf die Unterschiede. Unterschiede im Ablauf: Anstelle einer TID wird nur eine PID übergeben. Alle Parameter mit einem post_-Prefix haben hier das Prefix edit_! Also z.B. post_title => edit_title post_icon => edit_icon post_converturls => edit_converturls
HTTP-Keyword | Name | Beschreibung |
---|---|---|
POST | PID | Die Posting-ID des zu bearbeitenden Postings. |
Das hier ist nicht direkt Teil der XML API, sondern der POST-Schnittstelle, aber da wir schonmal hier sind ;) Der Pfad zum Skript lautet http://forum.mods.de/bb/newreply.php Ablauf:
HTTP-Keyword | Name | Beschreibung |
---|---|---|
POST | TID | Die Thread-ID zu der der Post gehören soll |
POST | SID | Die Session-ID, aber nur, wenn man sie nicht per Cookie übermittelt. Also nie. |
POST | token | token ist ein Sicherheitstoken um Leute wie uns (nein, nicht wirklich ;) ) draußenzuhalten. Es wird vermutlich intern zur Verarbeitung des Aufrufs benötigt und wird uns von der Seite schon fertig ausgeliefert: <input type="hidden" name="token" value="b5c7ad552bcd7063656b7b2fac1ae6eb"> |
POST | post_title | Der Name sagt alles, der Titel des Posts. |
POST | message | Nachrichteninhalt. Maximallänge: 15.000 Bytes bzw. rund 15 KB |
POST | post_converturls | Wenn dieser Parameter übertragen wird und 1 ist, werden [URL]-Tags automatisch eingefügt |
POST | post_disablebbcode | Wenn dieser Parameter übertragen wird und 1 ist, wird BB-Code für diesen Post deaktiviert |
POST | post_disablesmilies | Wenn dieser Parameter übertragen wird und 1 ist, werden keine Smilies erzeugt |
POST | submit | Sollte "Eintragen" als Wert haben. Ich weiß nicht ob das überprüft wird, aber es ist definitv cleaner. |
POST | post_icon | Das Icon des Posts.
Mögliche Werte:
|
Da sich der Ablauf und die Parameter sehr ähneln, verweise ich für weitere Informationen auf newreply.php und beschränke mich hier auf die Unterschiede. Unterschiede im Ablauf: Anstelle der TID wird die BID (Board-ID) übergeben.
HTTP-Keyword | Name | Beschreibung |
---|---|---|
POST | thread_title | Thread Titel |
POST | thread_subtitle | Thread Untertitel |
POST | thread_tags | Thread Tags |
POST | BID | Die Board-ID des Boards in dem der Thread erstellt werden soll. |
Eigentlich ist das relativ nutzlos, da sich das vermutlich eh nie ändern wird... ;D Ich glaube ich brauche hier nichts wirklich zu schreiben, praktisch alle Angaben hieraus kann man auch hardcoden. (Henne-Ei-Problem: Wenn ich settings.php aufrufe um den Basispfad (/settings/base-url) herauszufinden, woher habe ich ihn denn dann ;) )
Es gibt übrigens auch noch eine xml/settings.php, die bisher nirgends verwendet wird und die ich, soweit ich mich erinnern kann, auch noch nirgends verlinkt habe - vermutlich, weil sie ziemlich nutzlos ist - enos
<?xml version="1.0" encoding="utf-8" ?> <settings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://forum.mods.de/bb/forum.xsd" current-user-id="0"> <flags> <allow-dynamic-images value="0"/> <is-online value="1"/> </flags> <forum-title> <![CDATA[mods.de - Forum]]> </forum-title> <base-url> <![CDATA[http://forum.mods.de/bb]]> </base-url> <base-url-banners> <![CDATA[http://forum.mods.de/bb/img/head/]]> </base-url-banners> <banner> <![CDATA[banner-mde.jpeg]]> </banner> <replies-per-page>30 </replies-per-page> <threads-per-page>30 </threads-per-page> </settings>
Die thread.php ist für die Ausgabe von Threads mitsamt Posts zuständig. Gerüchteweise ist es irgendwie möglich die Ausgabe auf einen Post zu beschränken bzw. die Anzahl der Auszugebenden Posts zu verändern. Wie dies gemacht wird ist derzeit jedoch unbekannt. Normalerweise wird eine vollständige Seite (30 Posts) oder, wenn es nicht soviele Posts gibt, so viele Posts ausgegeben, bis es keine Posts mehr zum Ausgeben gibt. Anders gesagt ist data(/thread/posts/@count) nie größer als 30.
<?xml version="1.0" encoding="utf-8" ?> <thread xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://forum.mods.de/bb/forum.xsd" current-user-id="1224901" id="140831"> <title> <![CDATA[Gehirnsalat]]> </title> <subtitle> <![CDATA[wir unter uns]]> </subtitle> <number-of-replies value='165797' /> <number-of-hits value='5767761' /> <flags> <is-closed value="0" /> <is-sticky value="0" /> <is-important value="0" /> <is-announcement value="0" /> <is-global value="0" /> </flags> <in-board id="43" /> <firstpost> <post> <user id="19602"> <![CDATA[TriggerTG]]> </user> <date timestamp="1149182655">01.06.2006 19:24:15 </date> <in-thread id="140831" /> <in-board id="43" /> </post> </firstpost> <posts page="5528" offset="165810" count="1"> <post id="1243000252"> <user id="1224901" group-id="3"> <![CDATA[csde_rats]]> </user> <date timestamp="1312055567">30.07.2011 21:52:47 </date> <message> <edited count="2"> <lastedit> <user id="1224901"> <![CDATA[csde_rats]]> </user> <date timestamp="1312055985">30.07.2011 21:59:45 </date> </lastedit> </edited> <content> <![CDATA[So ich hab mal angefangen: [URL]http://mde-xml.docs.enkore.de/[/URL] *Le Fu: Muss noch kurz dem werten Gast Rechte geben *erledigt]]> </content> <title> </title> </message> <avatar id="59224"> <![CDATA[./avatare/german.gif]]> </avatar> <in-thread id="140831"> <![CDATA[Gehirnsalat]]> </in-thread> <in-board id="43" /> </post> </posts> </thread>
is-hidden
gibt an, ob der Post versteckt ist (is-hidden="texthidden"
).
HTTP-Keyword | Name | Beschreibung |
---|---|---|
GET | TID | Die Thread-ID des auszugebenden Threads.
Wenn keine Thread mit dieser ID existiert oder keine TID angegeben wurde, bekommt man lediglich ein <invalid-thread/>zurück. |
GET | PID | PID gibt eine Post-ID für einen Post an, der auf jeden Fall in der Ausgabe enthalten ist. Wenn in dem Thread kein Post mit dieser ID vorhanden ist, wird die erste Seite zurückgegeben. |
GET | page | Gibt die auszugebende Seite an.
Wenn der Thread nicht soviele Seiten hat, hat das Posts-Tag keine Kinder: <posts page="6700000" offset="200999970" count="0"/> |
GET | temp | Der temp-Parameter wird beim Erstellen eines Posts übergeben um Caching zu verhindern. Standardmäßig wird hier einfach der aktuelle Timestamp (z.B. 1312117403) übergeben. Hauptsache den Wert gabs vorher nicht.... |
GET | offset | Gibt die Anzahl der am Anfang zu überspringenden Posts an.
Es wird, sofern der Thread genug Posts hat, immer exakt mit dem offset-ten Post angefangen und von da an bis zum Threadende oder maximal 30 Posts ausgegeben.
Wenn der Thread nicht genug Posts hat, kommt ähnliches wie bei Page zurück: <posts offset="89999999999" count="0"/> |
GET | onlyPID | Wenn onlyPID gesetzt ist, wird nur das Posting mit dieser Posting-ID ausgegeben. Dadurch entfällt nicht die Angabe der TID. |
GET | update_bookmark | Wenn update_bookmark 1 ist (Standard: 0), dann wird das Lesezeichen auf den letzten ausgegeben Post verschoben (wie bei der normalen Threadanzeige also) |