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