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