API:Erweiterungen
Diese Seite ist Teil der Dokumentation der MediaWiki action API. |
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 ApiBase , manche Modultypen nutzen jedoch eine abgeleitete Basisklasse. Auch die Registrierungsmethode hängt vom Modultypen ab.
- Aktionsmodule
- Module, die einen Wert für den Haupt-
action
-Parameter bieten, sollten Unterklassen von ApiBase sein. Sie sollten mit dem SchlüsselAPIModules
inextension.json
registriert sein. - Formatmodule
- Module, die einen Wert für den Haupt-
format
-Parameter bieten, sollten Unterklassen von ApiFormatBase sein. Sie sollten mit dem SchlüsselAPIFormatModules
inextension.json
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
prop
,list
, odermeta
zuaction=query
bieten, sollten Unterklassen von ApiQueryBase (wenn nicht als Generator nutzbar) oder ApiQueryGeneratorBase sein (wenn als Generator nutzbar). Sie sollten mit einem der SchlüsselAPIPropModules
,APIListModules
, oderAPIMetaModules
inextension.json
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 ApiMain::moduleManager (für Action- und Formatmodule) und ApiQuery::moduleManager (für Abfrage-Submodule) registriert sein.
Implementierung
Präfix
In der Konstruktion deines API-Moduls kannst du, wenn du parent::__construct()
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 getAllowedParams() 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 ApiBase definierten PARAM_*
-Konstanten definiert, sind.
Das Beispiel zeigt die Syntax und einige der häufigeren PARAM_*
-Konstanten.
protected function getAllowedParams() {
return [
// Ein optionaler Parameter mit einem Standardwert
'simple' => 'value',
// Ein erforderlicher Parameter
'required' => [
ApiBase::PARAM_TYPE => 'string',
ApiBase::PARAM_REQUIRED => true,
],
// Ein Parameter, der mehrere Werte aus einer Liste akzeptiert
'variable' => [
// Die Standardwerte
ApiBase::PARAM_DFLT => 'foo|bar|baz',
// Alle möglichen Werte
ApiBase::PARAM_TYPE => [ 'foo', 'bar', 'baz', 'quux', 'fred', 'blah' ],
// Gibt an, dass mehrere Werte akzeptiert werden
ApiBase::PARAM_ISMULTI => true,
// Nutze standardmäßige "je-Wert"-Dokumentationsnachrichten
ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
],
// Ein standardmäßiger "Limit"-Parameter. Es ist am besten, nicht von diesem Standard abzuweichen.
'limit' => [
ApiBase::PARAM_DFLT => 10,
ApiBase::PARAM_TYPE => 'limit',
ApiBase::PARAM_MIN => 1,
ApiBase::PARAM_MAX => ApiBase::LIMIT_BIG1,
ApiBase::PARAM_MAX2 => ApiBase::LIMIT_BIG2,
],
];
}
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 execute() ausgeführt. Dieser Code nutzt normalerweise $this→extractRequestParams(), um die Eingabeparameter zu erhalten und wird $this→getResult() nutzen, um das ApiResult-Objekt zu erhalten, das zu jeder Ausgabe hinzugefügt wird.
Query-Prop-Submodule sollten $this→getPageSet() nutzen, um auf die zu bearbeitenden Seiten zuzugreifen.
Abfrage-Submodule, die als Generatoren genutzt werden können, müssen auch executeGenerator() implementieren, was an ApiPageSet übergeben wird und mit den generierten Seiten gefüllt werden sollte.
In diesem Fall sollte ApiResult
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 $this→getMain()→setCacheMode() erlauben.
Dies erfordert weiterhin, dass der Client die Parameter maxage
oder smaxage
übergibt, damit sie tatsächlich zwischengespeichert werden können.
Du kannst das Zwischenspeichern auch durch Anrufen von $this→getMain()→setCacheMaxAge() erzwingen.
Rufe für Abfragemodule nicht diese Methoden an. Du kannst das Zwischenspeichern stattdessen durch Implementation von getCacheMode() 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 needsToken()
, die das Token ausgibt, das dein Modul benötigt (wahrscheinlich das 'csrf'
Bearbeitungstoken).
Der API-Base-Code wird dann automatisch das Token validieren, das Clients in API-Abfragen in einem Parameter token
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 ApiQueryTokensRegisterTypes , um dein Token zu registrieren.
Master-Datenbankzugriff
Wenn dein Modul auf die Master-Datenbank zugreift, sollte es die Methode isWriteMode()
implementieren, um true
auszugeben.
Fehlermeldungen
ApiBase 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 $this→requireOnlyOneParameter().
- Wenn du sicherstellen musst, dass höchstens einer aus einer Reihe von Parametern angegeben wurde, verwende $this→requireMaxOneParameter().
- Wenn du sicherstellen musst, dass mindestens einer aus einer Reihe von Parametern angegeben wurde, verwende $this→requireAtLeastOneParameter().
- Wenn du sicherstellen musst, dass der Benutzer bestimmte Rechte hat, verwende $this→checkUserRightsAny().
- Wenn du sicherstellen musst, dass der Benutzer auf einer bestimmten Seite eine Aktion ausführen kann, verwende $this→checkTitleUserPermissions().
- Wenn der Benutzer gesperrt ist (und das für dein Modul von Bedeutung ist), setze das Objekt
Block
auf $this→dieBlocked().
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 $this→dieWithError() anzurufen, wobei du, wenn du StatusValue
mit der Fehlerinformation erhältst, es stattdessen an $this→dieStatus() übergeben kannst.
Wenn du eine Warnung statt eines Fehlers melden musst, nutze $this→addWarning() oder $this→addDeprecation(), 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 apihelp-$path-summary
-Nachricht, die eine einzeilige Beschreibung des Moduls sein sollte.
Wenn zusätzlicher Text benötigt wird, kann auch apihelp-$path-extended-description
erstellt werden.
Jeder Parameter benötigt eine apihelp-$path-param-$name
-Nachricht und Parameter, die PARAM_HELP_MSG_PER_VALUE
nutzen, benötigen auch einen apihelp-$path-paramvalue-$name-$value
für jeden Wert.
Mehr Details zur API-Dokumentation sind auf API:Lokalisation 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 Extension:<ExtensionName>/API
oder Unterseiten davon (z.B. CentralAuth , MassMessage oder StructuredDiscussions ).
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:
- APIGetAllowedParams - um die Parameterliste des Moduls zu ergänzen oder zu verändern
- APIGetParamDescriptionMessages - um die Parameterbeschreibungen des Moduls zu ergänzen oder zu verändern
- APIAfterExecute - um etwas zu tun, nachdem das Modul ausgeführt wurde (aber bevor das Ergebnis ausgegeben wurde)
- Nutze APIQueryAfterExecute für die Module
prop=
,list=
undmeta=
- Wenn das Modul in einem Generatormodul läuft, wird stattdessen APIQueryGeneratorAfterExecute angerufen
- Nutze APIQueryAfterExecute für die Module
Liste von Erweiterungen mit API-Funktion
Siehe Kategorie:API-Erweiterungen für Beispiele von Erweiterungen, die die API ergänzen oder erweitern.
Teste deine Erweiterung
- Besuche 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
getExamplesMessages()
angegeben hast, sollten unter "Beispiele" erscheinen, versuche sie anzuklicken. - Lasse URL-Parameter in der Abfrage-Zeichenkette aus und überprüfe die Antwort deiner Erweiterung.
- Die Beispiel-URLs, die du in
- Besuche Special:ApiSandbox und entdecke interaktiv deine API.
- Um zusätzliche Informationen über deine Erweiterung zu sehen: