Quelltext der Seite Wikipedia:Technik/Skin/JS/API

{{../../../!header
|Text=API-Aktionen mit JavaScript}}
Auf dieser Seite wird dargestellt, wie sich API-Abfragen sowie Manipulationen mit [[JavaScript]] programmieren lassen.

Einen Einstieg zur API („[[Programmierschnittstelle]]“) für [[MediaWiki]] gibt [[Wikipedia:Technik/Datenbank/API|Datenbank/API]].

== Überblick ==
Die grundlegende Technologie ist [[Ajax (Programmierung)|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 [[Rückruffunktion|Callback-Funktion]] möglich.

Primär ist nur der Kontakt mit derselben [[Domain (Internet)|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 [[Hypertext Transfer Protocol#HTTP GET|HTTP-GET]] möglich. Diese Fragen (<code>query</code>) kann im Prinzip jeder Teilnehmer im Internet stellen.

Aktivitäten, die in irgendeiner Weise das Projekt verändern, sind sicherheitsrelevant und lassen sich ausschließlich mit [[Hypertext Transfer Protocol#HTTP POST|HTTP-POST]] übermitteln; dies geht nicht mehr über eine einfache URL. Zur Verifizierung ist ein „Token“ erforderlich, der zuvor in der Arbeitsumgebung des Benutzers beschafft werden muss.<ref name="writeapi" /> Zu den Aktivitäten gehören:
* Schreiben von Seiten-Inhalten (<s>edit</s> <code>csrf</code>)
* Veränderungen der Beobachtungsliste (<code>watch</code>)
* E-Mail verschicken
* Administrator-Funktionen (Seitenlöschung, Benutzersperrung usw.)
{{Anker|deprecated-tokens-csrf}}
Bis 2015 <!-- MW1.24 --> waren für die nachstehenden Aktionen einzelne Tokens erforderlich gewesen:
<code>edit</code>, <code>move</code>, <code>options</code>, <code>email</code> sowie für Admins <code>delete</code>, <code>protect</code>, <code>block</code>, <code>unblock</code>, <code>import</code>. Inzwischen ist stattdessen einheitlich <code>csrf</code> ''([[Cross-Site-Request-Forgery]])'' zu benutzen.

Auch in eine einfache Abfrage gehen über HTTP immer Informationen über das zurzeit angemeldete Benutzerkonto ein, wenn sie aus einer Wiki-Seite heraus erfolgt; sie werden den Anmelde-Cookies entnommen: [//de.wikipedia.org/w/api.php?action=query&meta=tokens action=query&meta=tokens].

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

Die Abfrage (HTTP-GET) mit einer URL stimmt exakt überein mit der Übermittlung eines JS-Objekts, das die gleichen Parameterzuweisungen enthält.

=== 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.
* [http://api.jquery.com/category/ajax/ jQuery-Kategorie für Ajax]
** [http://api.jquery.com/jQuery.ajax/ jQuery.ajax()] – Basisfunktion mit umfangreicher Dokumentation; aber eher nicht direkt anzuwenden.
* Besonders interessante Funktionen sind:
** [http://api.jquery.com/jQuery.getJSON/ jQuery.getJSON()]
** [http://api.jquery.com/jQuery.post/ jQuery.post()]
Allerdings empfiehlt es sich, die Unterstützung durch das [[#mw|<code>mw</code>-Objekt]] in Anspruch zu nehmen, das die Handhabung weiter vereinfacht.

==== {{Anker|Callback}} Vereinbarung von Callback-Funktionen ====
Die folgenden Funktionen können auf die Abfrage-Instanz angewendet werden:
:; .done(fine)
:: Definiere <code>fine</code> als Funktion, die bei erfolgreicher Ausführung aufgerufen wird. Es kann auch ein Array von Funktionen angeben werden; sogar <code>null</code>.
::* <code>fine(data, textStatus, jqXHR)</code>
::** <code>data</code> sind die erfragten Nutzdaten (JSON-Objekt).
:; .fail(fault)
:: Definiere <code>fault</code> als Funktion, die im Fehlerfall aufgerufen wird. Es kann auch ein Array von Funktionen angeben werden; sogar <code>null</code>.
::* <code>fault(jqXHR, textStatus, errorThrown)</code>
:; .always(facility)
:: Definiere <code>facility</code> als Funktion, die immer aufgerufen wird (nach einer Antwort); sie erhält komplexe Informationen über Erfolg oder Misserfolg.
:; .then(facility)
:: Definiere <code>facility</code> als Funktion, die immer sofort aufgerufen wird (auch bereits vor Eintreffen einer Antwort); sie erhält komplexe Informationen über Erfolg oder Misserfolg, falls bereits eine Antwort vorliegt.
Sowohl die mittels <code>.done()</code> wie auch mittels <code>.fail()</code> vereinbarte Funktion bieten zwei Parameterwerte, die bei Bedarf ausgewertet werden können:
* <code>jqXHR</code> gibt Details zum [[XMLHttpRequest]] an.
* <code>textStatus</code> ist eine Zeichenkette, die in Fehlermeldungen und Protokollen vermerkt werden kann.
Technisch gesprochen geben die verschiedenen Abfrage-Funktionen ein Objekt vom Typ <code>jQuery.Promise</code> zurück, das es erlaubt, beliebig viele Rückruf-Funktionen zu registrieren. Sollte man mit der Registrierung einer solchen Callback-Funktion zu spät kommen und das erwartete Ereignis bereits geschehen sein, wird trotzdem sofort zurückgerufen.

== {{Anker|mw}} <code>mw</code>-Objekt ==
In allen Seiten unter MediaWiki ist das [[../mw|<code>mw</code>-Objekt]] vorhanden. Hier lässt sich ein besonderes Modul bereitstellen, das vereinfachte API-Abfragen unterstützt.
* Diese API-Kommunikation muss erst mittels [[../mw#Ladezeitpunkt|<code>.loader</code> geladen]] werden; Modul: <code>mediawiki.api</code> (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.
* Quellcodes: {{Phab|file=resources/src/mediawiki/api.js}}

=== <code>mw.Api</code> ===
; .Api(defaults)
:: Konstruiert ein neues API-Objekt, etwa: ''a''<syntaxhighlight lang="javascript" inline> = new mw.Api();</syntaxhighlight> oder ''a''<code style="white-space: nowrap;">&nbsp;= new mw.Api(''defaults'');</code>.
:: Die Klasse <code>mw.Api</code> vereinfacht das Arbeiten insofern, als standardmäßig fünf Werte intern vorbelegt sind. {{Anker|mw.Api.defaults}} Diese und beliebige andere können umdefiniert werden:
{| class="wikitable" style="margin-left: 4em;"
|-
|rowspan="2"| ''defaults''<code>.parameters</code>
| <code>.action</code> || <code>'query'</code>  || API-Aktion, auch <code>'edit'</code>, <code>'watch'</code> und viele andere möglich.
|-
| <code>.format</code> || <code>'json'</code>   || Anfrageformat
|-
|rowspan="3"| ''defaults''<code>.ajax</code>
| {{Anker|mw.Api.url}} <code>.url</code>
| <code>[[../mw#.util.wikiScript()|mw.util.wikiScript]]('api')</code>
| <code>/w/api.php</code><br />String, aber auch [[../mw#.Uri|mw.Uri]]
|-
| <code>.dataType</code> || <code>'json'</code> || Antwort des Servers (MIME etc.) formatieren
|-
| <code>.timeout</code>  || <code>30000</code>  || 30 Sekunden
|}
Danach sind für ''a'' folgende Funktionen verfügbar:
:; .abort() <!-- 1.27wmf.3  2015-10 Task 111245 Gerrit:236193 -->
:: Abbruch aller noch nicht beendeten Anfragen für dieses Objekt.
:; .ajax(pars, opts)
:: Frei konfigurierbare Abfrage; sollte nicht direkt benutzt werden.
:; .get(pars, opts)
:: Abfrage mit GET-Methode starten.
:: Gibt ein Objekt vom Typ <code>jQuery.Promise</code> zurück, auf das [[#Callback|Callback-Vereinbarungen]] angewendet werden können.
:; .getToken(tokenType)
:: Stelle einen Token bereit.
:; .normalizeAjaxOptions()
:: (eher intern benutzt)
:; .post(pars, opts)
:: Abfrage mit POST-Methode starten.
:: Gibt ein Objekt vom Typ <code>jQuery.Promise</code> zurück, auf das [[#Callback|Callback-Vereinbarungen]] angewendet werden können.
:; .postWithToken(tokenType, pars, opts)
:: Abfrage mit POST-Methode starten, dabei automatisch für erforderlichen Token sorgen.
* ''pars'' – Objekt mit aktuellen Parametern der Abfrage: ''Was'' soll abgefragt werden?
** Konkrete Angaben sind notwendig.
** Die Parameter sind gerade die, die in den Wiki-Dokumentationen zur API beschrieben sind. ''pars'' ist in erster Näherung die Umsetzung des [[Query-String]] in ein JavaScript-Objekt.
** ''defaults''<code>.parameters</code> ermöglicht Vorgabewerte.
* ''opts'' – Objekt mit Ajax-Optionen: ''Wie'' soll abgefragt werden?
** Früher war die Angabe von ''opts'' zwingend notwendig. Mittlerweile ist dieser Parameter optional. Wenn ''opts'' angegeben wird, darf es nicht <code>null</code> sein.
*** ''opts''<code>.url</code> – Optional; Standard: Vorgabe bei <code>new mw.Api()</code>
*** In ''opts''<code>.ok</code> war früher die Erfolgsfunktion zu vereinbaren. Das ist inzwischen [[#Callback|nachträglich zuzuweisen]].
**** Es war früher eine Kurzform möglich: Erfolgsfunktion <code>function</code> als ''opts'' → ''opts''<code>.ok</code>
*** Genauso war als ''opts''<code>.err</code> die Funktion für den Fehlerfall vereinbar, was ebenfalls inzwischen weggefallen ist.
** ''defaults''<code>.ajax</code> ermöglicht Vorgabewerte.
** Im Übrigen entsprechen die möglichen Optionen denen, die auch bei [http://api.jquery.com/jQuery.ajax/ jQuery.ajax()] als <code>settings</code> dokumentiert sind.
* ''tokenType'' – Zeichenkette: "csrf", "login", "watch", "patrol", "rollback", [[#deprecated-tokens-csrf|<s>"edit"</s>]], …

Generell sind bei <code>mw.Api</code> noch einige statische Informationen erhältlich:
:; .Api.errors[]
:: Liste der schweren Fehler, die auftreten können
:; .Api.warnings[]
:: Liste der Warnmeldungen, die auftreten können

=== Elementares Beispiel ===
Das folgende kleine Beispiel fragt nach Informationen über das aktuelle Wiki:
<syntaxhighlight lang="javascript" style="margin-left:2em">
var a = new mw.Api();
a.get( { meta: 'siteinfo' } )
 .done( function ( answer ) { console.log( answer ); } );
</syntaxhighlight>
* Zunächst wird als Variable <code>a</code> eine Instanz generiert.
* Auf diese Instanz wird eine get-Abfrage angewendet.
* Die Vorgabe für die Aktion ist <code>'query'</code> (Abfrage). Es muss nur noch näher spezifiziert werden, was für eine Abfrage erfolgen soll; hier das Objekt:
*: <syntaxhighlight lang="javascript" inline>{ meta: 'siteinfo' }</syntaxhighlight>
* Auf den Abfrage-Aufruf <code>.get()</code> wird die Funktion [[#Callback|<code>.done()</code>]] angewendet. Dies ist eine von mehreren Möglichkeiten, die Callback-Funktion zu vereinbaren.
** Als Argument von <code>.done()</code> 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.
Dies entspricht der Abfrage: [//de.wikipedia.org/w/api.php?action=query&meta=siteinfo de.wikipedia.org/w/api.php?action=query&meta=siteinfo]
* Die Antwort ist analog strukturiert.

=== <code>mw.user</code> ===
In der Komponente [[../mw#.user|<code>mw.user</code>]] des <code>mw</code>-Objekts gibt es eine Funktion, mittels der sich schnell und einfach der für die Ausführung von Aktionen erforderliche Token gewinnen lässt:
* <syntaxhighlight lang="javascript" inline>mw.user.tokens.get("editToken")</syntaxhighlight>
** Für Seitenbearbeitung und Neuanlage von Seiten.
* <syntaxhighlight lang="javascript" inline>mw.user.tokens.get("watchToken")</syntaxhighlight>
** 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 <code>mw.user</code> 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 <code>mediawiki.api</code> ohnehin geladen werden muss, kann gleichzeitig auch <code>mediawiki.user</code> abgefordert werden.

=== Zusatzmodule für <code>mw.Api</code> ===
Wenn die Aufgaben über Abfragen hinausgehen, sind unter [[mw:ResourceLoader/Default modules #mediawiki.api]] weitere Unterstützungsmodule dargestellt. Sie mussten bis Juni 2018<!-- T192623  gerrit 434179 --> beim Laden der Ressourcen in die Liste aufgenommen werden. Mittlerweile wurden sie jedoch in das generelle JS-API-Modul integriert, und separate Modul-Anforderungen müssten eliminiert werden.

Die nachstehenden Funktionen können nach Laden des Moduls benutzt werden.
* Sie sind auf ein mit <syntaxhighlight lang="javascript" inline>a=new mw.Api();</syntaxhighlight> generiertes ''a'' anzuwenden.
* Sie hatten gemeinsame Parameter:
** <code>ok</code> – Callback-Funktion im Erfolgsfall (optional; meist empfehlenswert). Sie erhält ggf. die gewünschten Daten durch Aufruf als <code>ok(arg)</code> übermittelt.
** <code>err</code> – Callback-Funktion im Fehlerfall (optional)
* Diese Funktionsparameter <code>ok</code> und <code>err</code> sind durch eine Neuerung überholt worden. Sofortiger Rückgabewert aller dieser Aufrufe ist ein Objekt vom Typ <code>jQuery.Promise</code> – auf dieses Objekt ''r'' kann man die [[#Callback|jQuery-Callback-Funktionen]] anwenden, also mit ''r''<code>.done(</code>''fine''<code>)</code> beliebig viele eigene <code>ok</code>-Funktionen registrieren, die aufgerufen werden, sobald das Ergebnis vom Server eintrifft.

<!--
<div style="margin-left: 2em; border: solid 2px #0000C0; padding-left: 0.5em">
Die Funktionsparameter <code>ok</code> und <code>err</code> sind ''deprecated'', aber trotzdem zurzeit noch Pflichtparameter.

Man kann jedoch vorübergehend beiden eine Blindfunktion übergeben:
<syntaxhighlight lang="javascript" style="border: none; padding: 0; margin-left: 2em">
   dummy  =  function() {};
</syntaxhighlight>
und die definitive Lösung bereits endgültig über <code>.done()</code> usw. realisieren.
</div> -->
; .getCategories(title<s>, ok, err, async</s>) {{Anker|.getCategories()}}
: Finde alle Kategorien, zu denen eine bestimmte Seite <code>title</code> gehört.
:* Hinweis: Für die aktuell betrachtete Seite ist dies auch über <code>[[../Variablen#wgCategories|wgCategories]]</code> feststellbar.
: Mit <code>async=false</code> ließ sich eine synchrone Abfrage ausführen; diese konnte jegliche Browser-Aktion blockieren, bis eine Antwort eintrifft.
: An <code>ok(arg)</code> wurde ein Array mit allen Titeln übergeben, sonst <code>false</code>.
: <s>Modul: <code>mediawiki.api.category</code></s>
; .getCategoriesByPrefix(prefix<s>, ok, err</s>) {{Anker|.getCategoriesByPrefix()}}
: Finde alle Kategorien, deren Titel mit <code>prefix</code> beginnt.
: An <code>ok(arg)</code> wurde ein Array mit allen Titeln übergeben.
: <s>Modul: <code>mediawiki.api.category</code></s>
; .getMessages(messages) {{Anker|.getMessages()}}
: Frage einen Satz von Systemnachrichten in der Benutzersprache ab.
:* Parameter-Format wie <code>ammessages</code> – Zeichenkette mit durch Pipes getrennter Liste von Bezeichnern, oder <code>"*"</code> für ziemlich viele, oder Array mit Zeichenketten.
: <s>Modul: <code>mediawiki.api.messages</code></s>
; .getUserInfo()
: Benutzergruppen und Rechte des momentanen Benutzers abfragen
: <s>Modul: <code>mediawiki.api.user</code></s>
; .isBlacklisted(title<s>, ok, err</s>) {{Anker|.isBlacklisted()}}
: Stelle fest, ob der Seitenname <code>title</code> auf einer schwarzen Liste steht.
::* Mehr unter [[mw:Extension:TitleBlacklist]]
: An <code>ok(arg)</code> wurde <code>true</code> oder <code>false</code> übergeben.
: Modul: <code>mediawiki.api.titleblacklist</code>
; .isCategory(title<s>, ok, err</s>) {{Anker|.isCategory()}}
: Stelle fest, ob eine Kategorie <code>title</code> existiert.
: An <code>ok(arg)</code> wurde <code>true</code> oder <code>false</code> übergeben.
: <s>Modul: <code>mediawiki.api.category</code></s>
; .loadMessages(messages) {{Anker|.loadMessages()}}
: Lädt einen Satz von Nachrichten in der aktuellen Benutzersprache und fügt sie <code>[[../mw#.messages|mw.messages]]</code> hinzu.
::* Parameter wie [[#.getMessages()|.getMessages()]]
: <s>Modul: <code>mediawiki.api.messages</code></s>
; .loadMessagesIfMissing(messages) {{Anker|.loadMessagesIfMissing()}}
: Lädt einen Satz von bislang fehlender Nachrichten in der aktuellen Benutzersprache und fügt sie <code>[[../mw#.messages|mw.messages]]</code> hinzu.
::* Parameter wie [[#.getMessages()|.getMessages()]]
: <s>Modul: <code>mediawiki.api.messages</code></s>
; .newSection(title, header, message<s>, ok, err</s>) {{Anker|.newSection()}}
: Hänge einen neuen Abschnitt an eine Seite an; kümmere dich selbst um einen geeigneten Token.
: Der Seiten-Name wird über <code>title</code> gesucht, <code>header</code> ist die Abschnittsüberschrift und <code>message</code> der Wikitext.
: <s>Modul: <code>mediawiki.api.edit</code></s>
; .parse(wikitext<s>, ok, err</s>) {{Anker|.parse()}}
: Transformiere den <code>wikitext</code> analog [[mw:API:Parsing wikitext #parse]].
: An <code>ok(arg)</code> wurde ein HTML-Text übergeben.
: <s>Modul: <code>mediawiki.api.parse</code></s>
; .postWithEditToken(params<s>, ok, err</s>) {{Anker|.postWithEditToken()}}
: Führe eine Seitenbearbeitung aus; kümmere dich selbst um einen geeigneten Token.
: <code>params</code> ist ein JS-Objekt mit Einzelheiten (identisch mit denen, die bei einem Aufruf von <code>.post()</code> anzugeben wären; also Seiten-Identifikation und neuer Text, auch Bearbeitungskommentar und „Kleine Änderung“).
: <s>Modul: <code>mediawiki.api.edit</code></s>
; .saveOption(single, value) {{Anker|.saveOption()}}
: Wert einer Benutzereinstellung setzen
:* ''single'' Schlüsselwort für die Einstellung
:* ''value'' Zeichenkette oder <code>null</code>
: <s>Modul: <code>mediawiki.api.options</code></s>
; .saveOptions(options) {{Anker|.saveOptions()}}
: Werte von Benutzereinstellungen setzen
:* ''options'' object als <code style="white-space: nowrap">{ name1: value1, name2: value2, ... }</code><!-- Gerrit:160308 1.25wmf23 2015-04 -->
: <s>Modul: <code>mediawiki.api.options</code></s>
; .unwatch(page<s>, ok, err</s>) {{Anker|.unwatch()}}
: Entferne <code>page</code> von der persönlichen Beobachtungsliste.
: <s>Modul: <code>mediawiki.api.watch</code></s>
; .watch(page<s>, ok, err</s>) {{Anker|.watch()}}
: Setze <code>page</code> auf die persönliche Beobachtungsliste.
: <s>Modul: <code>mediawiki.api.watch</code></s>

Quellcodes:
* {{Phab|project=mediawiki/extensions/TitleBlacklist|file=modules/mediawiki.api.titleblacklist.js|title=extensions/TitleBlacklist::api.titleblacklist.js}}

Der logischen Vollständigkeit halber ist <code>mediawiki.util</code> hier explizit mit angegeben. Tatsächlich würde bei der Auflösung der Anforderung durch den ResourceLoader die jeweils erforderliche Basis-Software auch selbsttätig nachgefordert werden; <code>mediawiki.api</code> stellt <code>mediawiki.util</code> sicher. Eine höhere Funktionalität wie <code>mediawiki.api.edit</code> sorgt automatisch für das Laden von <code>mediawiki.api</code> – es schadet aber auch nicht, dies von vornherein anzugeben, und könnte möglicherweise Abläufe beschleunigen.

== Auswertung des Ergebnisses ==
In vielen Fällen will man dem Ergebnis Daten entnehmen; namentlich bei einer <code>query</code>. Auch bei Aktivitäten liefert die Callback-Funktion eine Erfolgsmeldung.

Egal, auf welche Weise (mit oder ohne Nutzung der Funktionen in <code>mw.Api</code>) erhält die Callback-Funktion für eine erfolgreiche Abfrage ein strukturiertes Objekt; vorausgesetzt, dass bei der Anfrage das Resultat als JSON zurückgeliefert werden soll, wie das standardmäßig der Fall ist.

Je nach gestellter Frage ist der erste Parameter <code>data</code> in der Callback-Funktion unterschiedlich strukturiert. Die oberste Ebene ist immer ein Objekt; aber die erwarteten Komponenten sind möglicherweise nicht vorhanden, weil vermutete Seiten usw. überhaupt nicht existieren. Der direkte Zugriff auf Unterkomponenten würde dann einen Laufzeitfehler auslösen. Besser ist es, die Existenz der vermuteten Komponente jeweils abzuprüfen.

Einen ersten Überblick über die zu erwartende Struktur gibt eine interaktive Abfrage, deren [[Extensible Markup Language|XML]]-Ergebnis auf einer HTML-Seite dargestellt wird. Wie bei den im [[mw:API:Properties/de#revisions / rv (Versionen)|Manual]] als Beispiele angegebenen URL kann man sich an die sinnvolle Fragestellung herantasten; die Struktur des Ergebnisses wird dann identisch sein. Das Element <code>&lt;query></code> in XML ist gleichzeitig die Komponente <code>data.query</code> in JSON. Eine weitere Hilfe ist es, das eintreffende Objekt in einem JS-Debugger strukturiert darzustellen und dementsprechend die Programmstruktur zu entwickeln.

In vielen Fällen ist es sinnvoll, bei Definition einer Abfrage nach Seiten <syntaxhighlight lang="javascript" inline>indexpageids:true</syntaxhighlight> aufzunehmen. Das Ergebnis enthält dann auch ein Array mit den Seiten-Nummern, mit dessen Hilfe sich ggf. einfacher durch die einschlägige Komponente des Ergebnisses iterieren lässt.

Wenn auf die Abfrage mehr Einzelantworten lieferbar sind als mit einer Frage allein zulässigerweise beantwortet werden können, gibt es in der Antwort ein Element <syntaxhighlight lang="javascript" inline>data["query-continue"]</syntaxhighlight> – diese Komponente enthält einen Hinweis, ab welcher Seiten-Nummer usw. eine Nachfolge-Abfrage beginnen soll.

Wenn man eine unbestimmte Anzahl von Einzelergebnissen erwartet, gibt es die Möglichkeit, den jeweiligen Parameter ''xx''limit auf <code>"max"</code> zu setzen; dies bewirkt im Regelfall <code>500</code>. Außerdem wird zurückgemeldet, zu wie vielen Einzeldaten dieser Benutzer bei diesem Typ von Abfrage berechtigt ist. Ist man tatsächlich etwa nur an dem allerjüngsten Einzelergebnis interessiert, sollte das entsprechende ''xx''limit auf <code>1</code> gesetzt werden, um Netzwerk-Verkehr, Server-Belastung und Antwortzeit möglichst gering zu halten.

== Ausführliches Beispiel ==
<syntaxhighlight lang="javascript" style="margin-left:2em">
var found  =  function ( data ) {
   // Erfolgreich. Ergebnis analysieren.
   var i, page, pageids, pages, revisions,
       id     =  -1,
       query  =  data.query,
       k      =  0;
   if ( query ) {
      pageids  =  query.pageids;
      if ( pageids ) {
         id  =  pageids[ 0 ];
      }
      pages  =  query.pages;
      if ( pages  &&  id > 0 ) {
         page  =  pages[ id ];
         if ( page ) {
            revisions  =  page.revisions;
            if ( revisions ) {
               for ( i = 0;  i < revisions.length;  i++ ) {
                  if ( revisions[ i ].comment.indexOf( "rückgängig gemacht" )  >  0 ) {
                     k++;
                  }
               }   // for i
            }
         }
      }
   }
   window.console.info( "Die Hauptseite wurde " + k + " Mal zurückgesetzt." );
   if ( data[ "query-continue" ] ) {
      window.console.info( "Die Hauptseite wurde mehr als 100 Mal geändert." );
   }
};   // found()


var fault  =  function ( uhff ) {
   // Fehlgeschlagen.
   window.console.warn( "API-Abfrage hat nicht geklappt." );
   window.console.log( uhff );
};   // fault()


var fire  =  function () {
   // Löse eine Abfrage aus: Was sind die letzten 100 Versionen der Hauptseite?
   var p  =  { prop:         "revisions",
               rvlimit:      100,
               rvslots:      "main",
               indexpageids: true,
               titles:       "Wikipedia:Hauptseite"
             },
       q  =  new mw.Api();
   q.get( p ).done( found ).fail( fault );
};   // fire()


mw.loader.using( [ "mediawiki.api",
                   "mediawiki.util" ],
                 fire );
</syntaxhighlight>
* Zunächst stehen die Deklarationen der Einzelfunktionen.
* Abschließend, nachdem alle Einzelfunktionen bekannt sind, werden mit [[../ResourceLoader#.loader.using()|mw.loader.using]] die Module abgefordert. Sobald sie bereit sind, wird die Funktion <code>fire()</code> aufgerufen, die ja zuvor definiert wurde.
* [//de.wikipedia.org/w/api.php?action=query&prop=revisions&rvlimit=100&indexpageids=true&titles=Wikipedia:Hauptseite Diese Abfrage wird gestartet.]
* In der Funktion <code>found()</code> wird das Ergebnis analysiert. Dabei wird konservativ vorgegangen und das Fehlen jeder Komponente in Betracht gezogen.
* Das Argument <code>data</code> enthält die Komponente <code>query</code>, die der gleichnamigen Komponente der XML-Antwort entspricht.
* Weil die Anfrage <code>indexpageids</code> gefordert hatte, ist unter <code>query.pageids</code> ein Array verfügbar, das die <code>curid</code> aller gefundener Seiten aufführt. Es kommt vor, dass auch negative Seitennummern auftauchen, weil Seiten unzugänglich sind.
* Die Komponente <code>query.pages</code> ist zurzeit kein Array, sondern ein Objekt. Damit sind die einzelnen Seiten nicht unmittelbar zugreifbar. Es kann iteriert werden, oder das Array <code>query.pageids</code> für den Zugriff genutzt werden.
* Im konkreten Fall enthält <code>query.pageids</code> genau ein Element, das die momentane Seitennummer zum Namen <code>Wikipedia:Hauptseite</code> wiedergibt.
* Nachdem damit auf die (hier einzige) Seite <code>page</code> zugegriffen wurde, kann mit <code>page.revisions</code> ein Array ausgewertet werden.
* <code>rvslots:"main"</code> ist mittlerweile vorgeschrieben, obwohl es praktisch keine Anwendung gibt, bei der in einer Seite ein anderer „Slot“ als <code>main</code> verfügbar wäre. Fehlt die Angabe, wird darauf zurückgefallen. Im vorliegenden Beispiel wird jedoch auf die gesamte Seite zugegriffen; damit ist eine Auswertung der Slot-Eigenschaften nicht erforderlich.
* Falls eine Abfrage fortgesetzt werden soll, ist das durch Auswertung von <code style="white-space: nowrap">data[ "query-continue" ].revisions.rvcontinue</code> möglich; damit kann eine neue Abfrage konstruiert werden.
* Wenn die Abfrage völlig fehlschlägt, wird die Funktion <code>fault()</code> aufgerufen. Sie protokolliert das Objekt mit Details. Das Fehlen von zutreffenden Daten ist in diesem Sinne kein Fehlschlag, jedoch ungültige Parametersyntax oder unerreichbarer Server.

=== Code-Beispiel zu <code>query-continue</code> ===
<syntaxhighlight lang="javascript">
var api = new mw.Api(),
    carryon = function( queryContinue ) {
                 var params = { action: "query",
                                generator: "watchlistraw",
                                prop: "info",
                                gwrlimit: "max",
                                gwrnamespace: "0"
                              },
                     page;
      if ( queryContinue ) {
         params.gwrcontinue = queryContinue;
      }
      api.get( params, {
        Ok: function( args ) {
               for ( page in args.query.pages ) {
                  if ( args.query.pages[ page ].missing === "" ) {
                     Api.unwatch( args.query.pages[ page ].title );
                  }
               }   // for
               if ( args["query-continue"] ) {
                  carryon( args["query-continue"].watchlistraw.gwrcontinue );
               } else {
                  alert( "all done" );
               }
              }   // Ok()
             } );
            };   // carryon()
</syntaxhighlight>
Führt eine Ent-Beobachtung im ANR aus. Es wird das maximale Limit beobachteter Artikel abgerufen, diese werden auf unbeobachtet gesetzt; sollte es mehr als das Limit geben, dann wird erneut bis zum maximalen Limit abgerufen usw.

== {{Anker|cross|CORS}} Andere Wiki-Projekte ==
Mit einigen Einschränkungen ist es möglich, per API mit dem Inhalt eines anderen WMF-Projektes zu kommunizieren.

Aus Sicherheitsgründen sind derartige Aktionen außerhalb des eigenen Projektes an strikte Regeln gebunden. Die Erlaubnis zum Cross-Domain-Scripting öffnet eine fundamentale Sicherheitslücke im Konzept der [[Same-Origin-Policy]]. Ein von einer beliebigen fremden Website untergeschobener JavaScript-Code könnte fatale Folgen haben. Projektseiten der WMF kommunizieren jedoch, welchen anderen [[Domain (Internet)|Domains]] sie vertrauen und ermöglichen in diesem Rahmen [[Cross-Origin Resource Sharing]] (CORS).

Insbesondere ist zur Einhaltung der Sicherheitsregeln auch streng auf das identische Protokoll <code>http</code> bzw. <code>https</code> zu achten.

Am einfachsten ist es, ein fremdes Projekt lediglich abzufragen.
* [[mw:Manual:CORS]]

=== Beispiel für eine Abfrage in einer anderen Wikipedia ===
<syntaxhighlight lang="javascript" style="margin-left:2em">
var fire  =  function ( about, abroad ) {
   // Löse eine Frage nach der jüngsten Versionsgeschichte einer Interlanguage-Seite aus.
   // @param {string} about   -- Name/n der gewünschten Seite/n
   // @param {string} abroad  -- Zwei/Drei-Buchstaben-Code der anderen Wikipedia, etwa "en"
   var h  =  document.location.hostname,
       o  =  { url:    "//" + abroad + h.substr( h.indexOf( "." ) )
                            + mw.util.wikiScript( "api" )
             },
       p  =  { prop:   "revisions",
               titles: about
             },
       q  =  new mw.Api();
   p.origin  =  document.location.protocol + "//" + h;
   q.get( p, o ).done( found ).fail( fault );
};   // fire()
</syntaxhighlight>
* Die Option <code>o</code> setzt die URL der anderen Wikipedia zusammen.
** Genau genommen ist es ein Interlanguage, also die gleiche (beliebige) Projekt-Art in einer anderen Sprache.
** Mit <code>o.url</code> ist anzugeben, dass eine andere URL als die in <code>.Api</code> standardmäßig für das eigene Wiki vorgegebene benutzt werden soll.
** Die protokoll-relative URL ist hier möglich und sinnvoll; es wird das Protokoll der umgebenden Seite geerbt.
** [[../mw#.util.wikiScript()|<code>mw.util.wikiScript("api")</code>]] holt den gültigen Pfad-Namen für API-Abfragen.
** Genauso hätte dies in den <code>new mw.Api([[#mw.Api.defaults|defaults]])</code> bei Bildung der Instanz angegeben werden können, wenn <code>q</code> mehrfach zu diesem Zweck benutzt werden soll.
* Die aktuelle Frage wird wie üblich in <code>p</code> formuliert.
** Hinzu kommt aber eine Komponente <code>p.origin</code> zur Angabe des Absenders der Anfrage.
** Diese Objekt-Komponente wird beim Server daraufhin geprüft, ob sie exakt mit der umgebenden HTTP-Kommunikation übereinstimmt, und ob sie den Erwartungen entspricht.
** Dabei muss das aktuelle Protokoll festgestellt werden; <code>[[../Variablen#wgServer|wgServer]]</code> ist protokoll-relativ und eignet sich nicht.
* Danach kann die normale Abfrage erfolgen; das Ergebnis wird an <code>found()</code> übermittelt, bei Misserfolg <code>fault()</code> aufgerufen.

=== mediawiki.ForeignApi ===
Das zuvor anzufordernde Modul <code>mediawiki.ForeignApi</code> stellt Hilfsfunktionen bereit, die den Vorgang unterstützen.

Insbesondere wäre <code style="white-space:nowrap">new mw.Api(defaults)</code> durch <code style="white-space:nowrap">new mw.ForeignApi(URL,defaults)</code> zu ersetzen. Anschließend stehen alle Hilfsfunktionen bereit, die oben für das eigene Wiki erläutert sind.

<syntaxhighlight lang="javascript" style="margin-left:2em">
var fire  =  function ( about, abroad ) {
   // Löse eine Frage nach der jüngsten Versionsgeschichte einer Interlanguage-Seite aus.
   // @param {string} about   -- Name/n der gewünschten Seite/n
   // @param {string} abroad  -- Zwei/Drei-Buchstaben-Code der anderen Wikipedia, etwa "en"
   var host = document.location.hostname,
       url  = document.location.protocol + "//" 
              + abroad + host.substr( host.indexOf( "." ) )
              + mw.util.wikiScript( "api" ),
       prop = { prop:   "revisions",
                titles: about
              },
       qobj = new mw.ForeignApi( url );
   qobj.get( prop ).done( found ).fail( fault );
};   // fire()
</syntaxhighlight>

== REST ==
Um 2017 wurde eine auf [[Representational State Transfer|REST]] basierende Schnittstelle produktiv eingeführt. Ob das klassische Format dann langfristig weiterhin voll unterstützt werden würde, steht dahin. Bei Verwendung der Funktionen im mw-Objekt wäre aber anzunehmen, dass Änderungen im Format der Anforderungen und des Ablaufs sich hier innerhalb der von MediaWiki programmierten Software abspielen und die JS-Objekte für Auftrag und Rückmeldung auf Anwenderseite kompatibel bleiben. Ohnehin würde eine Umschaltung von einem Tag auf den anderen alle WMF-Projekte dauerhaft zusammenbrechen lassen; es wäre also zunächst nur eine zusätzliche Technologie.
* [[mw:RESTBase]]
* [https://www.mediawiki.org/api/rest_v1/ v1] – Verfügbare Funktionen
* [[mw:API/REST proposal]]

== Weiterentwicklung ==

=== api2.php ===
Es gibt Wünsche, die vorhandene Schnittstelle besser nutzbar zu machen. Dazu gehören Versionsinformationen, auf die sich eine Anforderung verlässt, und lokalisierte Nachrichten, sowie Verbesserungen in den Auswertungsmöglichkeiten des Ergebnisses. Wenn bei der Kontaktaufnahme mitgeteilt wird, auf welche API-Version sich die Programmierung verlässt, ist es möglich, dies völlig kompatibel umzusetzen, indem beim Fehlen einer derartigen Angabe konservativ geantwortet wird.
* [[mw:Requests for comment/API Future]]

== Weitere Informationen ==
* [[Wikipedia:Technik/Datenbank/API]] zum Angebot des Wiki-Servers
* [[mw:API:Main page]] – englischsprachige Dokumentation der Kernfunktionen; Stammseite auf [[MediaWiki]].
** nicht immer vollständig und aktuell
* Erweiterungen mit eigenen API-Abfragen unter [[mw:Category:API extensions|mw:API extensions]].
* [//de.wikipedia.org/w/api.php api.php] – automatisch generierte Dokumentation, die stets aktuell ist und neben Kernfunktionen auch die gültigen Erweiterungen enthält (englisch).

== Anmerkungen ==
<references>
<ref name="writeapi">
Zurzeit haben alle Benutzer, also auch ohne namentliche Anmeldung, das Recht <code>writeapi</code>. Allerdings ist zumindest der aktuelle Kontext einer Wiki-Seite erforderlich (Cookies), um Tokens zu generieren.

Dieser Sitzungs-Kontext entsteht automatisch durch bloßes Betrachten einer Wiki-Seite. Über das Cookie wird eine Sitzung zugeordnet, die noch nicht veraltet sein darf.
</ref>
</references>

[[Kategorie:Wikipedia:Technik/Skin/JavaScript|API]]