API: JSON version Two

API: JSON version Two

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.
  • All ApiResult methods that operate on a passed-in array (rather than internal gegevens) 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 start with an underscore are reserved for API metadata (following the lead of existing _element and _subelements ), 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 spil arrays or hashes. This is particularly useful to fix T12887.
  • The “*” property is deprecated te amparo 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 treated for you.
  • ApiFormatXml will no longer throw an exception if you leave behind 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 gegevens 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 flagrante booleans to ApiResult, and the API will automatically convert them ter responses to “version 1” clients to the old convention for boolean result parameters (empty-string for true and absent for false) for rearwards compatibility. However, this means that if you were violating this convention by returning a boolean “someKey“: true or false , then existing clients will most likely pauze! If your API module does this then you need to use the fresh 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 te ApiResult, also if you insert outer gegevens structures such spil JSON into ApiResult, you may be returning true or false values without realizing it.
  • Modules outputting spil < “key” : < “*” : “value” >> to avoid large strings ter XML attributes can now output spil < “key” : “value” >while still maintaining &lt,container&gt,&lt,key&gt, value &lt,/key&gt,&lt,/container&gt, ter XML format, using ApiResult::META_BC_SUBELEMENTS. Fresh code should use ApiResult::setSubelementsList() instead.
  • Modules outputting hashes spil [< “name” : “key1” , “*” : “value1” >,< “name” : “key2” , “*” : “value2” >] (due to the keys being invalid for XML) can now output spil < “key1” : “value1” , “key2” : “value2” >ter JSON while maintaining &lt,container&gt,&lt,voorwerp name= “key1” &gt, value1 &lt,/voorwerp&gt,&lt,voorwerp name= “key2” &gt, value2 &lt,/voorwerp&gt,&lt,/container&gt, te XML format, using ApiResult:setArrayType() with array META_TYPE ‘kvp’ or ‘BCkvp’ .
  • 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 &lt,rev&gt, knot when rvdiffto is not supplied and spil the value of a &lt,content&gt, subnode of the &lt,rev&gt, 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. &lt,attribute name= “Four::foo” &gt, ).

    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.

    3 thoughts on “API: JSON version Two

    1. You left behind to mention Binance for altcoin exchange. It has a low fees (0.10% or 0.05%) and supports many pairs of coins.

    2. Bittrex has temporarily closed registration to fresh users, unluckily making yobit the only option to sign up inbetween thesis two exchanges at the ogenblik. Spil others have mentioned, Binance is an other exchange to consider for similar services.

    Leave a Reply

    Your email address will not be published. Required fields are marked *