Wow, this list of changes fixes a lot of things that I've hated about our API for a long time (no more star properties! no more setIndexedTagName errors! consistent JSON formatting!). I feel like it's Christmas! Thanks for all your hard work on this Brad! It is much appreciated.
Kaldari On Fri, May 1, 2015 at 7:53 AM, Brad Jorsch (Anomie) <[email protected]> wrote: > After a lot of work, we're ready to provide a more sensible data layout for > format=json results (and also format=php). The changes are generally > backwards-compatible for API clients, but extension developers might have > some work to do. If your extension is maintained in Gerrit, much of the > necessary conversion has already been done for you (the major exception > being booleans that were violating the old API output conventions). > > The general theme is that the ApiResult arrays now have more metadata, > which is used to apply a backwards-compatible transformation for clients > that need it and optional transformation so JSON output needn't be limited > by restrictions of XML. At the same time, improvements were made to > ApiResult and ApiFormatXml to hopefully make it easier for developers to > use. > > Relevant changes include: > > - Several ApiResult methods were deprecated. If your extension is > maintained in Gerrit, these should have already been taken care of for > you > (with the exception of T95168 <https://phabricator.wikimedia.org/T95168 > > > where work is ongoing), but new code will need to avoid the deprecated > methods. > - 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 provided. This should reduce the > need > for passing ApiResult instances around just to be able to set metadata. > - Properties with names beginning with underscores are reserved for API > metadata (following the lead of existing "_element" and "_subelements"), > and will be stripped from output. Such properties may be marked as > non-metadata using ApiResult::setPreserveKeysList(), if necessary. > - PHP-arrays can now be tagged with "array types" to indicate whether > they should be output as arrays or hashes. This is particularly useful > to > fix T12887 <https://phabricator.wikimedia.org/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. > - Actual booleans should now be added to ApiResult, and will be > automatically converted to the old convention (empty-string for true and > absent for false) when needed for backwards compatibility. Code that was > violating the old convention will need to use the new > ApiResult::META_BC_BOOLS metadata property to prevent this conversion. > - Modules outputting as {"key":{"*":"value"}} to avoid large strings in > XML attributes can now output as {"key":"value"} while still maintaining > <container><key>value</key></container> in XML format, using > ApiResult::META_BC_SUBELEMENTS. New code should use > ApiResult::setSubelementsList() instead. > - Modules outputting hashes as > [{"name":"key1","*":"value1"},{"name":"key2","*":"value2"}] (due to the > keys being invalid for XML) can now output as > {"key1":"value1","key2":"value2"} in JSON while maintaining > <container><item > name="key1">value1</item><item name="key2">value2</item></container> in > XML format, using array types "kvp" or "BCkvp". > > I apologize for forgetting to announce this sooner. If developers need > assistance with API issues or code review for API modules, please do reach > out to me. > > > -- > Brad Jorsch (Anomie) > Software Engineer > Wikimedia Foundation > _______________________________________________ > Wikitech-l mailing list > [email protected] > https://lists.wikimedia.org/mailman/listinfo/wikitech-l _______________________________________________ Wikitech-l mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/wikitech-l
