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

Relevant changes include: ... - 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.

If developers need assistance with API issues or code review for API modules, please do reach out to me.

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(a)lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l