API:Extensions/de

Dieses Dokument behandelt die Erstellung eines API-Moduls in einer Erweiterung zur Nutzung mit MediaWiki 1.30 oder später.



Modulerstellung und Registrierung
Alle API-Module sind Unterklassen von, manche Modultypen nutzen jedoch eine abgeleitete Basisklasse. Auch die Registrierungsmethode hängt vom Modultypen ab.


 * Aktionsmodule
 * Module, die einen Wert für den Haupt- -Parameter bieten, sollten Unterklassen von sein. Sie sollten mit dem Schlüssel   in   registriert sein.


 * Formatmodule
 * Module, die einen Wert für den Haupt- -Parameter bieten, sollten Unterklassen von sein. Sie sollten mit dem Schlüssel   in   registriert sein. Es ist für eine Erweiterung sehr ungewöhnlich, ein hinzugefügtes Formatmodul zu benötigen.


 * Abfrage-Submodule
 * Module, die einen Wert für die Parameter,  , oder   zu   bieten, sollten Unterklassen von  (wenn nicht als Generator nutzbar) oder  sein (wenn als Generator nutzbar). Sie sollten mit einem der Schlüssel  ,  , oder   in   registriert sein.

In allen Fällen ist der Wert für den Registrierungsschlüssel ein Objekt mit dem Modulnamen (d.h. der Wert für den Parameter) als Schlüssel und dem Klassennamen als Wert. Module können unter gewissen Bedingungen mit den Hooks (für Action- und Formatmodule) und  (für Abfrage-Submodule) registriert sein.

Präfix
In der Konstruktion deines API-Moduls kannst du, wenn du anrufst, ein optionales Präfix für die Parameter deines Moduls angeben. (In der generierten Dokumentation für ein Modul erscheint dieses Präfix, wenn überhaupt, in Klammern in der Überschrift für das Modul.) Wenn dein Modul ein Abfrage-Submodul ist, ist ein Präfix erforderlich, da ein Client mehrere Submodule mit ihren eigenen Parametern in einer einzigen Abfrage aufrufen kann. Für Action- und Formatmodule ist das Präfix optional.

Parameter
Die meisten Module erfordern Parameter. Diese sind durch die Implementation von definiert. Der zurückgegebene Wert ist ein assoziatives Array, bei dem Schlüssel die Parameternamen (ohne Präfix) sind und Werte entweder der skalare Standardwert für den Parameter oder ein Array, das die Eigenschaften des Parameters durch Nutzung der in definierten  -Konstanten definiert, sind.

Das Beispiel zeigt die Syntax und einige der häufigeren -Konstanten.

Parameter sind mithilfe des MediaWiki-i18n-Mechanismus dokumentiert. Siehe #Dokumentation für Details.



Ausführung und Ausgabe
Der Code, der das Modul implementiert, wird über ausgeführt. Dieser Code nutzt normalerweise, um die Eingabeparameter zu erhalten und wird nutzen, um das -Objekt zu erhalten, das zu jeder Ausgabe hinzugefügt wird.

Query-Prop-Submodule sollten nutzen, um auf die zu bearbeitenden Seiten zuzugreifen.

Abfrage-Submodule, die als Generatoren genutzt werden können, müssen auch implementieren, was an  übergeben wird und mit den generierten Seiten gefüllt werden sollte. In diesem Fall sollte  allgemein nicht genutzt werden.

Caching
Standardmäßig werden API-Antworten als nicht zwischenspeicherbar ('Cache-Control: private') markiert!

Dies erfordert weiterhin, dass der Client die Parameter  oder   übergibt, damit sie tatsächlich zwischengespeichert werden können.

Rufe für Abfragemodule nicht diese Methoden an. Du kannst das Zwischenspeichern stattdessen durch Implementation von erlauben.

Stelle bitte in jedem Fall sicher, dass keine privaten Daten veröffentlicht werden.



Token-Behandlung
Wenn dein Actionmodul das Wiki auf irgendeine Art ändert, sollte es ein Token erfordern. Um dies automatisch zu behandeln, implementiere die Methode, die das Token ausgibt, das dein Modul benötigt (wahrscheinlich das   Bearbeitungstoken). Der API-Base-Code wird dann automatisch das Token validieren, das Clients in API-Abfragen in einem Parameter  angeben.

Wenn du kein Token nutzen möchtest, das Teil deines Kerns ist, sondern ein benutzerdefiniertes Token mit deinen eigenen Berechtigungsprüfungen, nutze den Hook, um dein Token zu registrieren.



Master-Datenbankzugriff
Wenn dein Modul auf die Master-Datenbank zugreift, sollte es die Methode  implementieren, um   auszugeben.



Fehlermeldungen
umfasst unterschiedliche Methoden zur Durchführung unterschiedlicher Prüfungen, zum Beispiel:


 * Wenn du sicherstellen musst, dass genau einer aus einer Reihe von Parametern angegeben wurde, verwende.
 * Wenn du sicherstellen musst, dass höchstens einer aus einer Reihe von Parametern angegeben wurde, verwende.
 * Wenn du sicherstellen musst, dass mindestens einer aus einer Reihe von Parametern angegeben wurde, verwende.
 * Wenn du sicherstellen musst, dass der Benutzer bestimmte Rechte hat, verwende.
 * Wenn du sicherstellen musst, dass der Benutzer auf einer bestimmten Seite eine Aktion ausführen kann, verwende.
 * Wenn der Benutzer gesperrt ist (und das für dein Modul von Bedeutung ist), setze das Objekt  auf.

Du wirst jedoch häufig auf Fälle treffen, in denen du einen eigenen Fehler melden musst. Der übliche Weg, um dies zu tun, ist anzurufen, wobei du, wenn du   mit der Fehlerinformation erhältst, es stattdessen an  übergeben kannst.

Wenn du eine Warnung statt eines Fehlers melden musst, nutze oder, wenn es sich um eine missbilligte Warnung handelt.

Dokumentation
Die API ist mithilfe des MediaWiki-i18n-Mechanismus dokumentiert. Benötigte Nachrichten haben Standardnamen, die auf dem "Pfad" des Moduls basieren. Für Action- und Formatmodule ist der Pfad der gleiche wie der Name des Moduls, der während der Registrierung genutzt wurde. Für Abfrage-Submodule ist es der Name mit dem Präfix "query+".

Jedes Modul benötigt eine -Nachricht, die eine einzeilige Beschreibung des Moduls sein sollte. Wenn zusätzlicher Text benötigt wird, kann auch  erstellt werden. Jeder Parameter benötigt eine -Nachricht und Parameter, die   nutzen, benötigen auch einen   für jeden Wert.

Mehr Details zur API-Dokumentation sind auf verfügbar.

Erweiterungen können auch zusätzliche API-Dokumentation auf Wikimedia pflegen. Diese sollte sich auf der Hauptseite der Erweiterung befinden oder, wenn mehr Platz benötigt wird, auf Seiten mit dem Namen  oder Unterseiten davon (z.B.,  oder ). Der API-Namensraum ist reserviert für die API des MediaWiki-Kerns.



Kernmodule erweitern
Seit MediaWiki 1.14 ist es möglich, Funktionen von Kernmodulen durch Nutzung des folgenden Hooks zu erweitern:


 * - um die Parameterliste des Moduls zu ergänzen oder zu verändern
 * - um die Parameterbeschreibungen des Moduls zu ergänzen oder zu verändern
 * - um etwas zu tun, nachdem das Modul ausgeführt wurde (aber bevor das Ergebnis ausgegeben wurde)
 * Nutze für die Module ,   und
 * Wenn das Modul in einem Generatormodul läuft, wird stattdessen angerufen



Liste von Erweiterungen mit API-Funktion
Siehe für Beispiele von Erweiterungen, die die API ergänzen oder erweitern.



Teste deine Erweiterung

 * Besuche [/api.php api.php] und navigiere zur generierten Hilfe für dein Modul oder Abfrage-Submodul. Die Hilfe-Information deiner Erweiterung sollte korrekt sein.
 * Die Beispiel-URLs, die du in  angegeben hast, sollten unter "Beispiele" erscheinen, versuche sie anzuklicken.
 * Lasse URL-Parameter in der Abfrage-Zeichenkette aus und überprüfe die Antwort deiner Erweiterung.
 * Besuche Special:ApiSandbox und entdecke interaktiv deine API.
 * Besuche, um zusätzliche Informationen über deine Erweiterung zu sehen.