API:Datenformate

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

Erhält die Ausgabe in JSON.

api.php?action=query&titles=Main%20page&format=json [In der ApiSandbox ausprobieren]

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 Parameter format 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)