forum.mods.de XML API Doku

Basierend auf PM-Gesprächen mit enos aus 2011. 2012 verschollen. 2014 aus DB-Dump wiederhergestellt.
  1. mods.de Forum XML API Dokumentation
  2. Applikationen
  3. Identifikatoren
  4. Login
  5. Logout
  6. Queries
  7. board.php
  8. boards.php
  9. bookmarks.php
  10. editreply.php
  11. newreply.php
  12. newthread.php
  13. settings.php
  14. thread.php
Anmerkung: threads.php fehlt.

mods.de Forum XML API Dokumentation

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!

Applikationen

Wenn ihr auch eine Applikation gebastelt habt, die die API verwendet, könnt ihr einfach einen Kommentar schreiben und ich trags dann hier ein! ;)

Identifikatoren

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.

Login

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:
  • 3600: Eine Stunde
  • 86400: Ein Tag
  • 604800: Eine Woche
  • 31536000: Ein Jahr

Logout

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.

Queries

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.

board.php

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>

HTTP-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.

boards.php

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>

bookmarks.php

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.

editreply.php

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.

newreply.php

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:

  1. newreply mit der gewünschten TID als GET-Parameter abrufen
  2. Das token rausfriemeln. Dafür bietet sich ein Regex an.
  3. Alle Felderchen brav ausfüllen und abschicken
Beachte: Es ist kein multipart/form-data Formular, sondern ein ganz normales!

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:
  • Icon: 32
  • Icon: 40
  • Icon: 34
  • Icon: 33
  • Icon: 41
  • Icon: 2
  • Icon: 1
  • Icon: 54
  • Icon: 38
  • Icon: 35
  • Icon: 28
  • Icon: 42
  • Icon: 36
  • Icon: 39
  • Icon: 37
  • Kein Icon: 0

newthread.php

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.

settings.php

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>

thread.php

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>

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)