format=json suffers from a number of shortcomings that make it more difficult to use than necessary. Many of thesis arise because XML wasgoed the innovador output format and the underlying gegevens structure of API responses wasgoed designed around this.
To address this, after discussion MediaWiki 1.25 introduces a fresh JSON response format. It is not the default, you only get results te the fresh format if you specify formatversion=Two , and it’s only for the json and php formats (and their human-readable jsonfm and phpfm variants).
Without specifying formatversion=Two , the results ter API responses that clients receive should be backwards-compatible. But there are some caveats:
- Modules that were previously outputting raw booleans ter JSON may now output those properties using the convention that has always bot the standard (for version 1): empty-string for true and absent key for false. Client code that acts on thesis booleans will likely pauze or warn if it doesn’t test for an absent key. Instances of this should be reported ter Phabricator so the API module can be immobile, please tag with #MediaWiki-API and the tag for the relevant extension.
- format=xml will now reversibly mangle tag and attribute names that are not valid XML, instead of just outputting invalid XML.
- Previously-announced cracking switches to loom entry parameter formatting, that are not actually part of this genérico result formatting switch but were made at about the same time.
API module implementers: ensuring rearwards compatibility Edit
The genérico theme is that the ApiResult arrays now have more metadata, which the API core code uses to apply a backwards-compatible transformation for clients that don’t request formatversion=Two , and optional transformation so JSON output needn’t be limited by limitations of XML. At the same time, ApiResult and ApiFormatXml are lighter for developers to use.
To ensure rearwards compatibility i.e. clients that don’t request formatversion=Two get the same results spil te previous releases developers of API modules may need to update code.
- Several ApiResult methods have bot deprecated. If your extension is maintained te Gerrit, thesis should have already bot taken care of for you (with the exception of T95168 where work is ongoing), but fresh code will need to avoid the deprecated methods.
- You should not use the deprecated methods getIsRawMode() and setRawMode() . Raw mode used to indicate that a result printer wished metadata keys such spil _element , now all printers need to treat “raw mode” gegevens.
Most of the switches to extensions that this switch necessitated are ter gerrit switch set I7b372. and topic:api-cleanup-PS25.
Switches to XML format Edit
format=xml does not have a fresh results format. There are some switches to XML results:
Switches here will mostly be on the back-end, the contemporáneo gegevens output to clients is intended to remain the same wherever possible. However, clients should be ready 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 switch 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 comeback the content spil the value of the <,rev>, knot when rvdiffto is not supplied and spil the value of a <,content>, subnode of the <,rev>, knot when it is.
For example, bug 43221 wasgoed immobilized by switching the names of attributes such spil “Four::foo” to gezond XML’s confinements. Ter the future, this would be motionless by either encoding the name (e.g. “_4.3A..3A.foo”) or by switching the structure of output te only the XML format (e.g. <,attribute name= “Four::foo” >, ).
On the MediaWiki code side, developers will see the following switches:
Related movie: 100% profit – Trade automatically with Bittrex PUMP Bot. Automóvil trade Bot and pump detector.
- The XML formatter will no longer diegene if ApiResult::setIndexedTagName() is forgotten. Instead, it will act spil 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 knot has both knot content (ApiResult::setContent()) and non-scalar attributes. Instead, it will simply shove the intended knot content into a subnode.
- Anything that’s hard-coding ‘*’ should be updated to use ApiResult::setContentValue().
- Extra metadata is available to hint at improved XML output.
The future of “version 1” JSON response format Edit
Te some future release the old format=json will be deprecated, and may eventually be liquidated.
You can use formatversion=Two te your requests ter MediaWiki 1.25, but do note that the output formatting isn’t entirely stable yet and might switch ter MediaWiki 1.26.
Switches to JSON output format Edit
With formatversion=Two , wij can make some useful switches:
- Terugwedstrijd booleans spil boolean true instead of empty-string. Where adequate, [note 1] comeback boolean false instead of omitting the property.
- Terugwedstrijd empty objects ter JSON spil <>, rather than .
- Have act=query’s “pages” be an array, instead of an object with pagina ids spil keys that can be difficult to iterate.
- Provide useful property names instead of ‘*’.
- Eliminate worthless indirection, e.g. < “text” : “. ” >instead of < “text” : < “*” : “. ” >> and < “key1” : “value1” , “key2” : “value2” >instead of [< “name” : “key1” , “*” : “value1” >,< “name” : “key2” , “*” : “value2” >] .
- The existing utf8 option is the default. A fresh ascii request parameter has bot introduced for clients who need all non-ASCII codepoints escaped.
If you see missed opportunities to make the above switches te existing formatversion=Two output, or if there are other switches that would make API output lighter to use te JSON, please let MediaWiki API developers know! Phabricator would be ideal (tag with #MediaWiki-API, and the adequate extension’s tag if applicable), or reply on the mediawiki-api mailing list.