API:Datenformate
Diese Seite ist Teil der Dokumentation der MediaWiki action API. |
Eingabe
Die API erhält ihre Eingaben über Parameter aus der HTTP-Abfrage im Format application/x-www-form-urlencoded
oder multipart/form-data
.
(unlike REST API, the Action API currently does not support application/json input format.)
Jedes Modul und Submodul hat seine eigenen Parameter, die in der Dokumentation und in action=help aufgelistet sind. Sie können auch über action=paraminfo erhalten werden.
Codierung
Alle Eingaben sollten gültiges UTF-8 in der NFC-Form sein. MediaWiki wird versuchen, andere Formate zu konvertieren, was zu einem Fehler führen kann.
Parameter mit mehreren Werten
Parameter, die mehrere Werte übernehmen, werden normalerweise übermittelt, indem die Werte durch das Pipe-Zeichen (|
) getrennt werden, z.B. param=value1|value2
.
Wenn ein Wert selbst das Pipe-Zeichen enthält, nutze U+001F (Einheitentrenner) als Trennung und stelle dem Wert das Präfix U+001F voran, z.B. param=%1Fvalue1%1Fvalue2
.
Wenn ein Parameter mehrere Werte akzeptiert, ist dies explizit in seiner Modul-Dokumentation aufgeführt.
Boolesche Parameter
Wenn ein boolescher Parameter in einer HTTP-Abfrage spezifiziert wird, wird dieser unabhängig von seinem Wert als true angenommen. Für einen false-Wert lasse den Parameter komplett weg.
Der beste Weg, um einen true-Parameter in einer HTTP-Abfrage zu spezifizieren, ist einParameter=
zu nutzen; das folgende =
stellt sicher, dass der Browser oder die HTTP-Bibliothek den "leeren" einParameter nicht verwirft.
Zeitstempel
Parameter, die Werte für Zeitstempel übernehmen, akzeptieren mehrere Zeitstempel-Formate:
- ISO-8601-Format:
2008-08-23T18:05:46Z
. - Internes Zeitstempel-Format von MediaWiki :
20080823180546
. - Internes Zeitstempel-Format von MySQL:
2008-08-23 18:05:46
. - UNIX-Zeitstempel-Format
1219514746
(Anzahl von Sekunden seit dem 1. Januar 1970).
Zeitstempel werden immer im ISO-8601-Format ausgegeben.
Ausgabe
Das Standard-Ausgabeformat in MediaWiki ist JSON. Von allen anderen Formaten wird abgeraten.
Das Ausgabeformat sollte immer durch Nutzung von format=yourformat
mit yourformat als einem der folgenden Formate spezifiziert werden:
json
: JSON-Format. (empfohlen)php
: Serialisiertes PHP-Format. (veraltet)xml
: XML-Format. (veraltet)txt
: PHP print_r()-Format. (entfernt in 1.27)dbg
: PHP var_export()-Format. (entfernt in 1.27)yaml
: YAML-Format. (entfernt in 1.27)wddx
: WDDX-Format. (entfernt in 1.26)dump
: PHP var_dump()-Format. (entfernt in 1.26)none
: Gibt eine leere Antwort aus. 1.21+
Beispiel
Antwort
{
"query": {
"pages": {
"217225": {
"pageid": 217225,
"ns": 0,
"title": "Main page"
}
}
}
}
Sofern nichts anderes angegeben ist, erlauben alle Module die Datenausgabe in allen generischen Formaten.
Um die Fehlerbehebung zu vereinfachen, haben alle generischen Formate "pretty-print-HTML"-Alternativen mit einem fm
-Suffix, z.B. jsonfm
.
JSON-Parameter
Die folgenden Parameter können mit format=json
und format=jsonfm
verwendet werden:
utf8
: Codiert die meisten (aber nicht alle) Nicht-ASCII-Zeichen als UTF-8, statt sie durch hexadezimale Fluchtabschnitte zu ersetzen. Typ: boolean.ascii
: Codiert alle Nicht-ASCII-Zeichen durch hexadezimale Fluchtabschnitte. Typ: boolean.formatversion
: Die Ausgabeformatierung. 1.25+1
: Rückwärts-kompatibles Format, nutzt*
-Schlüssel für Inhalts-Knoten, codiert Nicht-ASCII-Zeichen durch hexadezimale Fluchtabschnitte..2
: Modernes Format. Gibt die Antwort in einem saubereren Format aus, codiert die meisten Nicht-ASCII-Zeichen als UTF-8. (empfohlen)
callback
: Response in the JSON format, by wrapping the result in a JavaScript function call. For security reasons, these responses ignore any browser session cookies and respond without information specific to a current logged-in user. This means the following features are disabled for safety:- Tokens können nicht erhalten werden, sodass Aktionen, die Änderungen vornehmen nicht möglich sind.
- Der Client wird für alle Zwecke als anonymer (d.h. nicht angemeldeter) Benutzer behandelt, auch nachdem er sich über action=login angemeldet hat. Dies bedeutet, dass Module, die zusätzliche Rechte erfordern, nicht funktionieren, es sei denn, anonyme Benutzer dürfen diese nutzen.
Zusätzliche Anmerkungen
- Die Ausgabeformate XML und PHP sind missbilligt, werden aber noch verwendet. Clients, die in PHP geschrieben sind, sollten es vermeiden, das PHP-Format zu nutzen, da dies grundsätzlich unsicher ist. Es wird derzeit nur aufgrund seiner Popularität gepflegt.
- Es gibt viele Konvertierungsbibliotheken und Online-Konvertierer, um JSON-Antworten in andere Formate zu konvertieren — zum Beispiel konvertiert JSON-CSV in CSV.
- Feed-Module wie der Letzte-Änderungen-Feed überschreiben die Standard-Ausgabeformate und nutzen RSS oder Atom, wie es in ihrem Parameter
feedformat
spezifiziert ist. In diesen Fällen wird das im Parameterformat
spezifizierte Format nur genutzt, wenn es einen Fehler gibt.
Siehe auch
- API:Fehler und Warnungen - Enthält Formate von Warnungen und Fehlern.
- Gewartet von MediaWiki Interfaces Team.
- Echtzeit-Chat (IRC): #mediawiki-core connect
- Problem-Tracker: Phabricator MediaWiki-Action-API (Problem melden)