Wikipedia:Technik/Skin/JS/API

Vorlage:Überschriftensimulation 1 Auf dieser Seite wird dargestellt, wie sich API-Abfragen sowie Manipulationen mit JavaScript programmieren lassen.

Einen Einstieg zur API („Programmierschnittstelle“) für MediaWiki gibt Hilfe:API.

Überblick

Die grundlegende Technologie ist Ajax.

Dort steht das „A“ für ‚asynchron‘ – das bedeutet, dass die Aktion nur angestoßen wird. Sie läuft unabhängig im Hintergrund ab. Sofort nach dem Start wird mit der nächstfolgenden JavaScript-Anweisung fortgesetzt. In der Regel wünscht man, dass die ausgeführte Funktion wieder Kontakt mit dem auslösenden Skript aufnimmt; zumindest, um zu melden, ob die Aktion erfolgreich oder nicht ausgeführt wurde. Dies ist ausschließlich über eine Callback-Funktion möglich.

Primär ist nur der Kontakt mit derselben Domain möglich, von deren HTML-Seite im Browser das Skript gestartet wurde. Auf Wiki-Seiten sind jedoch Mechanismen aktiviert, mittels derer auch mit einem anderen Projekt kommuniziert werden kann; zumindest von einer anderen Wikipedia oder von Commons Daten abgerufen werden können.

Abfragen und Aktionen

Einfache Fragen nach öffentlich zugänglichen Informationen sind mit HTTP-GET möglich. Diese Fragen (query) kann im Prinzip jeder Teilnehmer im Internet stellen.

Aktivitäten, die in irgendeiner Weise das Projekt verändern, sind sicherheitsrelevant. Sie können nur von angemeldeten Benutzern ausgeführt werden. Ausschließlich mit HTTP-POST lassen sich Aktionen übermitteln; dies geht nicht mehr über eine einfache URL. Zur Verifizierung ist ein „Token“ erforderlich, der zuvor in der Arbeitsumgebung des angemeldeten Benutzers beschafft werden muss. Zu den Aktivitäten gehören:

• Schreiben von Seiten-Inhalten (edit)
• Veränderungen der Beobachtungsliste
• E-Mail verschicken
• Administrator-Funktionen (Seitenlöschung, Benutzersperrung usw.)

JSON

Für die Nutzung der API mit JavaScript empfiehlt sich durchgängig das JSON-Format; sowohl für Anfragen wie auch für die Interpretation der Antwort.

jQuery

In allen Seiten von MediaWiki steht auch die Skriptbibliothek jQuery zur Verfügung. Sie vereinfacht das Arbeiten stark, indem eine Reihe von Basisfunktionen passend zum aktuellen Browser verfügbar gemacht werden. Diese werden auch laufend den Neuentwicklungen der Browser angepasst und können je nach deren Fähigkeiten geeignete Details festlegen, um eine möglichst effiziente Abarbeitung zu sichern.

• jQuery-Kategorie für Ajax
  • jQuery.ajax() – Basisfunktion mit umfangreicher Dokumentation; aber eher nicht direkt anzuwenden.
• Besonders interessante Funktionen sind:
  • jQuery.getJSON()
  • jQuery.post()

Allerdings empfiehlt es sich, die Unterstützung durch das mw-Objekt in Anspruch zu nehmen, das die Handhabung weiter vereinfacht.

Vereinbarung von Callback-Funktionen

Die folgenden Funktionen können auf die Abfrage-Instanz angewendet werden:

.done(fine)

Definiere fine als Funktion, die bei erfolgreicher Ausführung aufgerufen wird.

• fine(data, textStatus, jqXHR)
  • data sind die erfragten Nutzdaten (JSON-Objekt).

.fail(fault)

Definiere fault als Funktion, die im Fehlerfall aufgerufen wird.

• fault(jqXHR, textStatus, errorThrown)

.always(facility)

Definiere facility als Funktion, die immer aufgerufen wird; sie erhält komplexe Informationen über Erfolg oder Misserfolg.

Sowohl die mittels .done() wie auch mittels .fail() vereinbarte Funktion bieten zwei Parameterwerte, die bei Bedarf ausgewertet werden können:

• jqXHR gibt Details zum XMLHttpRequest an.
• textStatus ist eine Zeichenkette, die in Fehlermeldungen und Protokollen vermerkt werden kann.

mw-Objekt

In allen Seiten unter MediaWiki ist das mw-Objekt vorhanden. Hier lässt sich ein besonderes Modul bereitstellen, das vereinfachte API-Abfragen unterstützt.

• Diese API-Kommunikation muss erst mittels .loader geladen werden; Modul: mediawiki.api (Es könnte sein, dass es bereits vorhanden ist, weil ein anderes Skript es schon benutzt hatte; aber davon darf nicht ausgegangen werden.)
• Die Programmierung in diesem Modul verwendet soweit möglich Funktionen aus jQuery und versieht sie mit Routine-Informationen zur Wiki-Anwendung.
• Quellcode: Vorlage:MwGerrit

mw.Api

.Api(defaults)

Konstruiert ein neues API-Objekt, etwa: a= new mw.Api(); oder a = new mw.Api(defaults);

Danach sind für a folgende Funktionen verfügbar:

.ajax(pars, opts)

Frei konfigurierbare Abfrage; sollte nicht direkt benutzt werden.

.get(pars, opts)

Abfrage mit GET-Methode

.normalizeAjaxOptions()

eher intern

.post(pars, opts)

Abfrage mit POST-Methode

.unwatch()

.watch()

.Api.errors[]

Liste der schweren Fehler, die auftreten können

.Api.warnings[]

Liste der Warnmeldungen, die auftreten können

Vereinfacht das Arbeiten insofern, als standardmäßig intern vorbelegt:

defaults (für neue Instanz)

pars	action	'query'	API-Aktion, auch 'edit'
	format	'json'	Anfrageformat
opts	url	mw.util.wikiScript('api')	/w/api.php
	dataType	'json'	Antwort des Servers (MIME etc.)
	timeout	30000	30 Sekunden

• pars – Objekt mit aktuellen Parametern der Abfrage: Was soll abgefragt werden?
  • Konkrete Angaben sind notwendig.
• opts – Objekt mit Ajax-Optionen: Wie soll abgefragt werden?
  • Beim Aufruf darf opts nicht weglassen werden, und darf nicht null sein.
  • Die Erfolgsfunktion opts.ok muss angegeben werden.
  • Kurzform möglich: Erfolgsfunktion function als opts → opts.ok
  • opts.url – Optional; Standard: Vorgabe bei new mw.Api()

Beispiel

Das folgende kleine Beispiel fragt nach Informationen über den aktuellen Benutzer:

var a = new mw.Api();
a.get( { meta: 'userinfo' } )
 .done( function ( answer ) { console.log( answer ); } );

• Zunächst wird als Variable a eine Instanz generiert.
• Auf diese Instanz wird eine get-Abfrage angewendet.
• Die Vorgabe für die Aktion ist 'query' (Abfrage). Es muss nur noch näher spezifiziert werden, was für eine Abfrage erfolgen soll; hier das Objekt:

  { meta: 'userinfo' }

• Auf den Abfrage-Aufruf .get() wird die Funktion .done() angewendet. Dies ist eine von mehreren Möglichkeiten, die Callback-Funktion zu vereinbaren.
  • Als Argument von .done() wurde eine anonyme Funktion gewählt. Sie protokolliert das Resultat auf einer Konsole. Genauso könnte hier der Name einer separat definierten Funktion angegeben werden.

mw.user

In der Komponente mw.user des mw-Objekts gibt es eine Funktion, mittels der sich schnell und einfach der für die Ausführung von Aktionen erforderliche Token gewinnen lässt:

• mw.user.tokens.get("editToken")
  • Für Seitenbearbeitung und Neuanlage von Seiten.
• mw.user.tokens.get("watchToken")
  • Um Seiten zu beobachten oder nicht mehr zu beobachten.

Je nachdem, mit welchen Rechten Benutzer ausgestattet sind und wie das Projekt konfiguriert ist, sind weitere Arten möglich.

• Die Komponente mw.user steht möglicherweise nicht von Beginn an zur Verfügung. Es empfiehlt sich, die eigentlichen Funktionen erst auszuführen, nachdem alle Module geladen sind. Weil mediawiki.api ohnehin geladen werden muss, kann gleichzeitig auch mediawiki.user abgefordert werden.

Zusatzmodule

Wenn die Aufgaben über Abfragen hinausgehen, sind unter mw:ResourceLoader/Default modules #mediawiki.api weitere Unterstützungsmodule dargestellt. Sie müssen beim Laden der Ressourcen in die Liste aufgenommen werden.