API:Erweiterungen

From mediawiki.org
This page is a translated version of the page API:Extensions and the translation is 88% complete.
Outdated translations are marked like this.
Languages:
Erweiterungen:

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üssel APIModules in extension.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üssel APIFormatModules in extension.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, oder meta zu action=query bieten, sollten Unterklassen von ApiQueryBase (wenn nicht als Generator nutzbar) oder ApiQueryGeneratorBase sein (wenn als Generator nutzbar). Sie sollten mit einem der Schlüssel APIPropModules, APIListModules, oder APIMetaModules in extension.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 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:

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.
  • Besuche Special:ApiSandbox und entdecke interaktiv deine API.
  • Um zusätzliche Informationen über deine Erweiterung zu sehen:
api.php?action=paraminfo&modules=myext [In der ApiSandbox ausprobieren]
Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Extensions/de&oldid=6166053"