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.
 * You should not use the deprecated methods  and  . Raw mode used to indicate that a result printer wanted metadata keys such as  ; now all printers need to handle "raw mode" data.
 * All ApiResult methods that operate on a passed-in array (rather than internal data) are now static, and static versions of all relevant data- and metadata-manipulation methods are available. This should reduce the need for passing ApiResult instances around just to be able to set metadata.
 * Properties that begin with an underscore are reserved for API metadata (following the lead of existing  and  ), and are stripped from output. You can indicate that a property beginning with an underscore is not metadata using ApiResult::setPreserveKeysList.
 * You can tag PHP arrays with "array types" to indicate whether they should be output as arrays or hashes. This is particularly useful to fix T12887.
 * The  property is deprecated in favor of a properly-named property and special metadata to identify it for XML format and for back-transformation. Use ApiResult::setContentValue instead of ApiResult::setContent and all the details are handled for you.
 * ApiFormatXml will no longer throw an exception if you forget to call ApiResult::setIndexedTagName!
 * ApiFormatXml will now reversibly mangle tag and attribute names that are not valid XML, instead of irreversibly mangling spaces and outputting invalid XML for other stuff.
 * ApiResult will now validate data added (e.g. adding resources or non-finite floats will throw an exception) and auto-convert objects. The ApiSerializable interface can be used to control object conversion, if __toString or cast-to-array is inappropriate.
 * You can now add actual booleans to ApiResult, and the API will automatically convert them in responses to "version 1" clients to the old convention for boolean result parameters (empty-string for true and absent for false) for backwards compatibility. However, this means that if you were violating this convention by returning a boolean  or , then existing clients will probably break! If your API module does this then you need to use the new ApiResult::META_BC_BOOLS metadata property to prevent this conversion for "version 1" clients. You should check your API module code for setting boolean values in ApiResult; also if you insert external data structures such as JSON into ApiResult, you may be returning   or   values without realizing it.
 * Modules outputting as  to avoid large strings in XML attributes can now output as   while still maintaining   in XML format, using ApiResult::META_BC_SUBELEMENTS. New code should use  instead.
 * Modules outputting hashes as  (due to the keys being invalid for XML) can now output as   in JSON while maintaining   in XML format, using ApiResult:setArrayType with array META_TYPE   or.

Most of the changes to extensions that this change necessitated are in gerrit change set I7b372... and topic:api-cleanup-PS25.

Changes to XML format
does not have a new results format. There are some changes to XML results:


 *  From API/Architecture_work/Planning 

Changes here will mostly be on the back-end; the actual data output to clients is intended to remain the same wherever possible. However, clients should be prepared for the following:
 * Result structure may no longer match the JSON format.
 * Tag and attribute names may be encoded when not conforming to XML requirements.
 * Result structure may change depending on the specific query. For example, passing both rvprop=content and rvdiffto=prev to prop=revisions would previously omit the diff from the result (bug 55371) (it should be throwing an error, but that's another bug). Now this will return the content as the value of the &lt;rev> node when  is not supplied and as the value of a &lt;content> subnode of the &lt;rev> node when it is.

For example, bug 43221 was fixed by changing the names of attributes such as "4::foo" to fit XML's restrictions. In the future, this would be fixed by either encoding the name (e.g. "_4.3A..3A.foo") or by changing the structure of output in only the XML format (e.g. ).

On the MediaWiki code side, developers will see the following changes:


 * The XML formatter will no longer die if ApiResult::setIndexedTagName is forgotten. Instead, it will act as if that were called with something generic (e.g. ApiResult::setIndexedTagName( $array, '_v' )).
 * The XML formatter will no longer (be supposed to) raise an error when a node has both node content (ApiResult::setContent) and non-scalar attributes. Instead, it will simply shove the intended node content into a subnode.
 * Anything that's hard-coding '*' should be updated to use ApiResult::setContentValue.
 * Additional metadata is available to hint at improved XML output.

The future of "version 1" JSON response format
In some future release the old format=json will be deprecated, and may eventually be removed.

Using the new JSON results format
You can use  in your requests in, but do note that the output formatting isn't entirely stable yet and might change in MediaWiki 1.26.

Changes to JSON output format

 *  XXX from mediawiki-api-announce mailing 

With, we can make some useful changes:


 * Return booleans as boolean true instead of empty-string. Where appropriate, return boolean false instead of omitting the property.
 * Return empty objects in JSON as {}, rather than [].
 * Have action=query's "pages" be an array, instead of an object with page ids as keys that can be difficult to iterate.
 * Provide useful property names instead of '*'.
 * Eliminate useless indirection, e.g.  instead of   and   instead of.
 * The existing  option is the default. A new   request parameter has been introduced for clients who need all non-ASCII codepoints escaped.

If you see missed opportunities to make the above changes in existing  output, or if there are other changes that would make API output easier to use in JSON, please let MediaWiki API developers know! Phabricator would be ideal (tag with #MediaWiki-API, and the appropriate extension's tag if applicable), or reply on the mediawiki-api mailing list.