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! Für Actionmodule kannst du das Zwischenspeichern durch Anrufen von erlauben. This still requires clients pass the  or   parameters to actually enable caching. You can force caching by also calling.

For query modules, do not call those methods. You can allow caching by instead implementing.

In either case, be sure that private data is not exposed.

Token-Behandlung
If your action module changes the wiki in any way, it should require a token of some kind. To have this handled automatically, implement the  method, returning the token that your module requires (probably the   edit token). The API base code will then automatically validate the token that clients provide in API requests in a  parameter.

If you don't want to use a token that is part of core, but rather a custom token with your own permission checks, use hook to register your token.

Master-Datenbankzugriff
If your module accesses the master database, it should implement the  method to return.

Fehlermeldungen
includes several methods for performing various checks, for example,


 * If you need to assert that exactly one of a set of parameters was supplied, use.
 * If you need to assert that at most one of a set of parameters was supplied, use.
 * If you need to assert that at least one of a set of parameters was supplied, use.
 * If you need to assert that the user has certain rights, use.
 * If you need to assert that the user can take an action on a particular page, use.
 * If the user is blocked (and that matters to your module), pass the  object to.

But you will often run into cases where you need to raise an error of your own. The usual way to do that is to call, although if you have a  with the error information you could pass it to  instead.

If you need to issue a warning rather than an error, use or  if it's a deprecation warning.

Dokumentation
The API is documented using MediaWiki's i18n mechanism. Needed messages generally have default names based on the module's "path". For action and format modules, the path is the same as the module's name used during registration. For query submodules, it's the name prefixed with "query+".

Every module will need a  message, which should be a one-line description of the module. If additional help text is needed,  may be created as well. Each parameter will need a  message, and parameters using   will also need a   for each value.

More details on API documentation are available at.

Extensions may also maintain extra API documentation on Wikimedia. This should be located on the extension's main page or, if more space is required, on pages named  or subpages thereof (e.g., , or ). The API namespace is reserved for the API of MediaWiki core.

Kernmodule erweitern
Since MediaWiki 1.14, it's possible to extend core modules' functionality using the following hooks:


 * - to add or modify the module's parameter list
 * - to add or modify the module's parameter descriptions
 * - to do something after the module has been executed (but before the result has been output)
 * Use for ,   and   modules
 * If the module is run in generator mode, will be called instead

Liste von Erweiterungen mit API-Funktion
See for examples of extensions that add to or extend the API.

Testen Sie Ihre Erweiterung
Your extension's help information should be correct.
 * Visit [/api.php api.php] and navigate to the generated help for your module or query submodule.
 * The example URLs you provided in  should appear under "Examples", try clicking them.
 * Omit and mangle URL parameters in the query string, check your extension's response.
 * Visit Special:ApiSandbox and interactively explore your API.
 * Visit to see additional information about your extension.