When does this go live? On Friday, May 1, 2015, Ryan Kaldari <rkald...@wikimedia.org> wrote:
> 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) < > bjor...@wikimedia.org <javascript:;>> > 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 > > Wikitech-l@lists.wikimedia.org <javascript:;> > > https://lists.wikimedia.org/mailman/listinfo/wikitech-l > _______________________________________________ > Wikitech-l mailing list > Wikitech-l@lists.wikimedia.org <javascript:;> > https://lists.wikimedia.org/mailman/listinfo/wikitech-l _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
