Return fields

The API-global parameter "ha_returnfields" makes it possible to filter API-output server-side. The syntax used for filtering is based on very simple XML-Xpath..

Note: Non existing returnfields are ignored. You do not need to provide ha_returnfields filters for responsefields, responsefields are always added to the response. Except for responsefield "profilepicture", because there is a large amount of data within that node that you could filter.

For example with "users.get" you could add to ha_returnfields "/user/firstname,/user/lastname". The response will result in only the firstname and lastname.

Example XML-response:

<?xml version="1.0" encoding="UTF-8" ?>
<users_get_result>
        <user>
                <firstname>Gorilla</firstname>
                <lastname>Api</lastname>
        </user>
<info>
        <timestamp_difference>6</timestamp_difference>
        <running_milliseconds>84</running_milliseconds>
        <secure_connection>false</secure_connection>
</info>
</users_get_result>

Another way is using a astrix (*), for example you can use "users.get" with returnfield "/user/birthday/*". This will get you all fields within "birthday" of each element.

Example XML-response:

<?xml version="1.0" encoding="UTF-8" ?>
<users_get_result>
        <user>
                <birthday>
                        <year>1976</year>
                        <month>12</month>
                        <day>22</day>
                        <age>32</age>
                </birthday>
        </user>
        <info>
                <timestamp_difference>6</timestamp_difference>
                <running_milliseconds>87</running_milliseconds>
                <secure_connection>false</secure_connection>
        </info>
</users_get_result>

You can also use the "//" modifier to filter on nodes where ever they are in the nodetree, for example with "media.get" and returnfield "//src" will result in the image source urls for all media sizes.

Example XML-response:

<?xml version="1.0" encoding="UTF-8"?>
<media_get_result>
        <media>
                <icon_small>
                        <src>http://94.100.116.115/205150001-205200000/205166401-205166500/205166437_1_R4lg.jpeg</src>
                </icon_small>
                <icon_medium>
                        <src>http://94.100.116.115/205150001-205200000/205166401-205166500/205166437_2_R4lg.jpeg</src>
                </icon_medium>
                <icon_large>
                        <src>http://94.100.116.115/205150001-205200000/205166401-205166500/205166437_3_R4lg.jpeg</src>
                </icon_large>
                <icon_extralarge>
                        <src>http://94.100.116.115/205150001-205200000/205166401-205166500/205166437_4_R4lg.jpeg</src>
                </icon_extralarge>
                <image>
                        <src>http://94.100.116.115/205150001-205200000/205166401-205166500/205166437_5_R4lg.jpeg</src>
                </image>
                <image_fullscreen>
                        <src>http://94.100.116.115/205150001-205200000/205166401-205166500/205166437_6_R4lg.jpeg</src>
                </image_fullscreen>
                <square_large>
                        <src>http://94.100.116.115/205150001-205200000/205166401-205166500/205166437_14_R4lg.jpeg</src>
                </square_large>
                <square_extralarge>
                        <src>http://94.100.116.115/205150001-205200000/205166401-205166500/205166437_16_R4lg.jpeg</src>
                </square_extralarge>
        </media>
        <info>
                <timestamp_difference>6</timestamp_difference>
                <running_milliseconds>117</running_milliseconds>
                <secure_connection>false</secure_connection>
        </info>
</media_get_result>