API:JSON version 2/de

leidet an einer Reihe von Mängeln, die die Verwendung stärker erschweren als nötig. Viele davon treten auf, da XML das ursprüngliche Ausgabeformat war und die zugrunde liegende Datenstruktur der API-Antworten darum herum entwickelt wurde.

Um dies zu verbessern, wurde nach einer Diskussion in MediaWiki 1.25 ein neues JSON-Antwortformat eingeführt. Es ist kein Standard, du erhältst die Ergebnisse nur in dem neuen Format, wenn du  spezifizierst und es ist nur für die Formate   und   (und die menschenlesbaren Varianten   und  ) verfügbar.



Aufrechterhaltung der Rückwärtskompatibilität

 *  API result formatting changes for JSON (formatversion=2) aus der mediawiki-api-announce-Mailingliste

Wenn  nicht spezifiziert wird, sollten die Ergebnisse in der API-Antwort, die Clients erhalten, immer rückwärtskompatibel sein. Es gibt jedoch zwei Vorbehalte:


 * Module, die zuvor unformatierte boolesche Werte in JSON ausgegeben haben, können diese Eigenschaften nun mit der Konvention ausgeben, die (für Version 1) der Standard war: Leere Zeichenkette für true und fehlender Schlüssel für false. Clientcode, der diese booleschen Werte verarbeitet, wird wahrscheinlich abbrechen oder eine Warnung ausgeben, wenn nicht auf einen fehlenden Schlüssel geprüft wird. Diese Fälle sollten im Phabricator gemeldet werden, sodass das API-Modul repariert werden kann, bitte markiere sie mit #MediaWiki-API und der Markierung für die entsprechende Erweiterung.
 * wird nun Namen von Markierungen und Attributen, die kein gültiges XML sind, verarbeiten, statt einfach ungültiges XML auszugeben.
 * Zuvor angekündigte grundlegende Änderungen, um die Formatierung von Eingabeparametern zu speichern, die kein Teil der allgemeinen Änderung der Ergebnisformatierung sind, aber zur gleichen Zeit angekündigt wurden.



API-Modul-Implementierer: Sicherstellung der Rückwärtskompatibilität

 *  XXX

Das allgemeine Thema ist, dass die ApiResult-Arrays nun mehr Metadaten enthalten, die der Code des API-Kerns nutzt, um eine rückwärtskompatible Umwandlung für Clients anzuwenden, die  nicht abfragen und optional umzuwandeln, sodass JSON-Ausgaben nicht den Beschränkungen von XML unterliegen. Gleichzeitig sind  und   für Entwickler einfacher zu nutzen.

Um Rückwärtskompatibilität sicherzustellen – d.h. dass Clients, die  abfragen, nicht die gleichen Ergebnisse wie in vorherigen Versionen erhalten – müssen Entwickler von API-Modulen möglicherweise den Code aktualisieren.


 * Unterschiedliche ApiResult-Methoden sind veraltet. Wenn deine Erweiterung in entwickelt wird, sollte dies bereits für dich erledigt sein (mit Ausnahme von T95168, woran gearbeitet wird), jedoch muss bei neuem Code vermieden werden, veraltete Methoden zu nutzen.
 * Du solltest die veralteten Methoden  und   nicht nutzen. Raw-Modus, genutzt, um anzugeben, dass ein Ergebnisdrucker Metadaten-Schlüssel wie   verwendet; nun müssen alle Drucker Daten aus dem "Raw-Modus" verarbeiten.
 * Alle ApiResult-Methoden, die mit einem übergebenen Array (statt internen Daten) arbeiten, sind nun statisch und statische Versionen aller relevanten Methoden zur Manipulation von Daten und Metadaten sind verfügbar. Dies sollte die Notwendigkeit zur Übergabe von ApiResult-Instanzen reduzieren, um Metadaten setzen zu können.
 * Eigenschaften, die mit einem Unterstrich beginnen, sind für API-Metadaten reserviert (angelehnt an die existierenden  und  ) und werden aus der Ausgabe entfernt. Du kannst mit ApiResult::setPreserveKeysList angeben, dass eine Eigenschaft, die mit einem Unterstrich beginnt, keine Metadaten ist.
 * Du kannst PHP-Arrays mit "Array-Typen" markieren, um anzugeben, ob sie als Arrays oder Hashes ausgegeben werden sollen. Dies ist besonders hilfreich, um T12887 zu beheben.
 * Die Eigenschaft  ist veraltet, stattdessen wird eine korrekt benannte Eigenschaft und spezielle Metadaten bevorzugt, um es für das XML-Format und die Rück-Umwandlung zu identifizieren. Nutze ApiResult::setContentValue statt ApiResult::setContent und alle Details werden für dich erledigt.
 * ApiFormatXml wird keine Ausnahme mehr ausgeben, wenn du vergisst, ApiResult::setIndexedTagName anzurufen!
 * ApiFormatXml wird nun Namen von Markierungen und Attributen, die kein gültiges XML sind, verarbeiten, statt Leerzeichen unumkehrbar zu verarbeiten und ungültiges XML für andere Dinge auszugeben.
 * ApiResult wird nur hinzugefügte Daten validieren (z.B. wird eine Ausnahme ausgegeben, wenn Ressourcen oder unendliche Zahlen hinzugefügt werden) und Objekte automatisch konvertieren. Die ApiSerializable-Oberfläche kann genutzt werden, um die Objekt-Konvertierung zu kontrollieren, wenn __toString oder cast-to-array unangemessen sind.
 * Du kannst nun boolesche Werte zu ApiResult hinzufügen und die API wird sie in Antworten an "Version-1"-Clients in die alte Konvention für boolesche Ergebnisparameter (leere Zeichenkette für true und keine für false) umwandeln, um Rückwärtskompatibilität sicherzustellen. Wenn du jedoch gegen diese Konventionen verstößt, indem du einen booleschen  oder   zurückgibst, werden die Clients möglicherweise abbrechen! Wenn dein API-Modul dies tut, musst du die neue Metadaten-Eigenschaft ApiResult::META_BC_BOOLS nutzen, um die Konvertierung für "Version-1"-Clients zu verhindern. Du solltest den Code deines API-Moduls darauf prüfen, ob boolesche Werte in ApiResult gesetzt werden; auch darauf, ob externe Datenstrukturen wie JSON in ApiResult eingefügt werden, da du möglicherweise  - oder  -Werte zurückgibst, ohne es zu merken.
 * Modulausgaben wie, um lange Zeichenketten in XML-Attributen zu vermeiden, können nun   ausgeben, während   im XML-Format bei Nutzung von ApiResult::META_BC_SUBELEMENTS weiterhin unterstützt wird. Neuer Code sollte stattdessen  nutzen.
 * Module, die Hashes wie  ausgeben (da die Schlüssel für XML ungültig wären) können nun als   in JSON ausgeben werden, während   im XML-Format bei Nutzung von ApiResult:setArrayType mit dem Array META_TYPE,   oder   weiterhin unterstützt wird.

Die meisten Änderungen an Erweiterungen, die für diese Änderungen erforderlich waren, befinden sich im Gerrit-Änderungssatz I7b372... und topic:api-cleanup-PS25.



Änderungen am XML-Format
hat kein neues Ergebnisformat. Es gibt einige Änderungen an XML-Ergebnissen:


 *  Aus API/Architecture work/Planning 

Änderungen gibt es hauptsächlich am Backend; die Datenausgabe Clients soll soweit möglich gleich bleiben. Clients sollten sich jedoch auf folgendes vorbereiten:
 * Die Ergebnisstruktur stimmt möglicherweise nicht mit dem JSON-Format überein.
 * Namen von Markierungen und Attributen können codiert werden, wenn sie XML-Anforderungen nicht erfüllen.
 * Abhängig von der jeweiligen Abfrage kann sich die Ergebnisstruktur ändern. Wenn beispielsweise rvprop=content und rvdiffto=prev an prop=revisions übergeben werden, wäre zuvor der Diff des Ergebnisses weggelassen worden (bug 55371) (es sollte ein Fehler ausgegeben werden, dies ist jedoch ein anderer Fehler). Nun wird der Inhalt als Wert des Knotens &lt;rev> ausgegeben, wenn  nicht übergeben wird und als Wert eines Unterknotens &lt;content> des Knotens &lt;rev>, wenn er übergeben wird.

Beispielsweise wurde Bug 43221 behoben, indem die Namen von Attributen wie "4::foo" geändert wurden, um die XML-Einschränkungen zu erfüllen. In Zukunft soll dies behoben werden, indem entweder der Name codiert wird (z.B. "_4.3A..3A.foo") oder die Struktur der Ausgabe in reines XML-Format geändert wird (z.B. ).

Auf Seiten des MediaWiki-Codes werden Entwickler folgende Änderungen sehen:


 * Der XML-Formatierer wird nicht länger abbrechen, wenn ApiResult::setIndexedTagName vergessen wird. Stattdessen wird so verfahren, wie wenn es mit etwas generischem angerufen worden wäre (z.B. ApiResult::setIndexedTagName( $array, '_v' )).
 * Der XML-Formatierer wird nicht länger einen Fehler ausgeben, wenn ein Knoten sowohl Knoten-Inhalt (ApiResult::setContent) als auch nicht-skalare Attribute enthält. Stattdessen wird der beabsichtige Knoteninhalt einfach in einen Unterknoten verschoben.
 * Alles, was mit '*' hart codiert ist, sollte aktualisiert werden, um ApiResult::setContentValue zu nutzen.
 * Zusätzliche Metadaten sind verfügbar, um auf eine verbesserte XML-Ausgabe hinzuweisen.



Die Zukunft des "Version-1"-JSON-Ausgabeformats
In einer zukünftigen Veröffentlichung wird das alte format=json veraltet sein und eventuell entfernt werden.



Nutzung des neuen JSON-Ausgabeformats
Du kannst  in deinen Abfragen in  nutzen, beachte jedoch, dass das Ausgabeformat noch nicht ganz stabil ist und sich in MediaWiki 1.26 ändern kann.



Änderungen am JSON-Ausgabeformat

 *  API result formatting changes for JSON (formatversion=2) aus der mediawiki-api-announce-Mailingliste

Mit  können wir einige nützliche Änderungen vornehmen:


 * Boolesche Werte als boolesches true statt als leere Zeichenkette zurückgeben. Wo dies angemessen ist, boolesches false zurückgeben, statt den Parameter wegzulassen.
 * Leere Objekte in JSON als {} statt als [] zurückgeben.
 * action=querys "Seiten" ein Array sein lassen, statt eines Objektes mit Seiten-IDs als Schlüsseln, die schwierig zu iterieren sein können.
 * Nützliche Eigenschaftennamen anbieten, anstatt '*'.
 * Nutzlose Umwege entfernen, z.B.  statt   und   statt.
 * Die existierende Option  ist der Standard. Ein neuer Abfrageparameter   wurde für Clients eingeführt, bei denen alle Nicht-ASCII-Codepunkte mit Escape-Zeichen versehen werden müssen.

Wenn dir fehlende Möglichkeiten auffallen, um die oben genannten Änderungen in der existierenden -Ausgabe vorzunehmen oder wenn es andere Änderungen gibt, die es erleichtern würden, die API-Ausgabe in JSON zu nutzen, lass es bitte die MediaWiki-API-Entwickler wissen! Phabricator wäre ideal (markiert mit #MediaWiki-API und, sofern möglich, dem entsprechenden Tag der Erweiterung) oder antworte in der mediawiki-api-Mailingliste.