TracNav
Batch Processing
The API method batch.process allows you to execute multiple (dependent) API-calls at once. E.g. retrieving a list of items and using data of that list to retrieve other information. This can save a lot of API-calls and which would speed up your application. You should use the batch processing together with specifying the returnfields to limit the size of the result.
Note:
- Batch.process is only available in version 2.0 / beta_2 and up.
- To use Batch.process you do not need user authorization.
- Batch.process works up to 10 API-calls
E.g., in the following usecase we're gonna retrieve a list of users (by username) and then retrieve their media-item (profile picture).
Without using the batch processing you will need to:
- Retrieve list of users using API-call users.getByUsername
- Process the list and collect all the mediaid's
- Do another API-call media.get with all the mediaid's
With batch.process step 2 and 3 are done by the API-server saving alot of roundtrips:
- Combine the retrieve users and retrieve media in 1 API-call batch.process
The batch.process API-call accept 1 parameter, "request". This parameter will consist of a comma-seperated list of API-calls. The combined API-calls do not need to have all the oauth_* parameters, these are inherited from the batch.process API-call (also oauth accesstoken). E.g.:
The first API-call:
apicall-1:
{
ha_method: "users.getByUsername",
username: "kilian,derkmdt,marijn-s",
ha_fancylayout: "false",
ha_format: "xml",
ha_version: "2.0"
}
As query string with url-encoded key & value:
ha_method=users.getByUsername&username=kilian%2Cderkmdt%2Cmarijn-s&ha_fancylayout=false&ha_format=xml&ha_version=2.0
Will retrieve a list of users by username.
The second API-call:
apicall-2:
{
ha_method: "media.get",
username: "0(mediaid)",
ha_fancylayout: "false",
ha_format: "xml",
ha_version: "2.0"
}
As query string with url-encoded key & value:
ha_method=media.get&mediaid=0%28mediaid%29&ha_fancylayout=false&ha_format=xml&ha_version=2.0
Will retrieve a list of media, where "0(mediaid)" tells the API-server to pick all fields named "mediaid" from the first batch.process API-call.
The "request"-parameter will look like this:
request = ha_method=users.getByUsername&username=kilian%2Cderkmdt%2Cmarijn-s&ha_fancylayout=false&ha_format=xml&ha_version=2.0,ha_method=media.get&mediaid=0%28mediaid%29&ha_fancylayout=false&ha_format=xml&ha_version=2.0
which consists of:
request = {querystring-apicall-1},{querystring-apicall-2}
The resulting API-call will look like this:
http://data.hyves-api.nl/?ha_fancylayout=false&ha_format=xml&ha_method=batch.process&ha_version=2.0&oauth_consumer_key=NV8n_5peMXHRJ14Xhr_vqYEG&oauth_nonce=&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1272354348&oauth_token=YXRfMjkzNTlfdz1f180WCEJ1W5AgnjF-vQ%3D%3D&oauth_version=1.0&request=ha_method%3Dusers.getByUsername%26username%3Dkilian%252Cderkmdt%252Cmarijn-s%26ha_fancylayout%3Dfalse%26ha_format%3Dxml%26ha_version%3D2.0%2Cha_method%3Dmedia.get%26mediaid%3D0%2528mediaid%2529%26ha_fancylayout%3Dfalse%26ha_format%3Dxml%26ha_version%3D2.0&oauth_signature=DuzySdWqBjLbMjoRwS3UHxdbb5M%3D
Executing this API-call will give us the following answer:
<?xml version="1.0" encoding="UTF-8"?> <batch_process_result> <request> <users_getByUsername_result> <user> <userid>0054e2e70a72538869018047cc45664b2f</userid> <displayname>Derk</displayname> <nickname>Derk :)</nickname> <firstname>Derk</firstname> <lastname>Braakman</lastname> <gender/> <birthday> <year/> <month/> <day/> <age/> </birthday> <friendscount>251</friendscount> <url>http://derkmdt.hyves.nl/</url> <mediaid>00953c9a5a7e549a052099e0d3a2fdcd4c</mediaid> <countryid>00da0d7e3a352207e824bf85791df6cbcb</countryid> <cityid/> <created>1105225200</created> <languagelocale>nl_NL</languagelocale> </user> <user> <userid>00eb4a83be37ec2bad7ea81b7685fd959b</userid> <displayname>Kilian</displayname> <nickname>Kilian</nickname> <firstname>Kilian</firstname> <lastname>Marjew</lastname> <gender/> <birthday> <year/> <month/> <day/> <age/> </birthday> <friendscount>239</friendscount> <url>http://kilian.hyves.nl/</url> <mediaid>0029f0f9578b37ccf55a0f5ac198ba8c17</mediaid> <countryid>00da0d7e3a352207e824bf85791df6cbcb</countryid> <cityid/> <created>1095717600</created> <languagelocale>nl_NL</languagelocale> </user> <user> <userid>0086c0f270b9df851fb5541326db452b2c</userid> <displayname>Marijn</displayname> <nickname>Marijn</nickname> <firstname>Marijn</firstname> <lastname/> <gender/> <birthday> <year/> <month/> <day/> <age/> </birthday> <friendscount>191</friendscount> <url>http://marijn-s.hyves.nl/</url> <mediaid>0076ca7ee406a185766f9bf24b35aa20db</mediaid> <countryid>00da0d7e3a352207e824bf85791df6cbcb</countryid> <cityid/> <created>1107212400</created> <languagelocale>nl_NL</languagelocale> </user> <info> <timestamp_difference>0</timestamp_difference> <running_milliseconds>87</running_milliseconds> <secure_connection>false</secure_connection> </info> </users_getByUsername_result> </request> <request> <media_get_result> <media> <mediaid>00953c9a5a7e549a052099e0d3a2fdcd4c</mediaid> <userid>0054e2e70a72538869018047cc45664b2f</userid> <title>profielfoto</title> <description/> <mediatype>image</mediatype> <icon_small> <width>43</width> <height>50</height> <src>http://94.100.120.17/794800001-794850000/794808401-794808500/794808491_1_vrPF_1.jpeg</src> </icon_small> <icon_medium> <width>65</width> <height>75</height> <src>http://94.100.120.17/794800001-794850000/794808401-794808500/794808491_2_vrPF_1.jpeg</src> </icon_medium> <icon_large> <width>104</width> <height>120</height> <src>http://94.100.120.17/794800001-794850000/794808401-794808500/794808491_3_vrPF_1.jpeg</src> </icon_large> <icon_extralarge> <width>174</width> <height>200</height> <src>http://94.100.120.17/794800001-794850000/794808401-794808500/794808491_4_vrPF_1.jpeg</src> </icon_extralarge> <image> <width>435</width> <height>499</height> <src>http://94.100.120.17/794800001-794850000/794808401-794808500/794808491_5_vrPF_1.jpeg</src> </image> <image_fullscreen> <width>609</width> <height>700</height> <src>http://94.100.120.17/794800001-794850000/794808401-794808500/794808491_6_vrPF_1.jpeg</src> </image_fullscreen> <square_large> <width>75</width> <height>75</height> <src>http://94.100.120.17/794800001-794850000/794808401-794808500/794808491_14_vrPF_1.jpeg</src> </square_large> <square_extralarge> <width>120</width> <height>120</height> <src>http://94.100.120.17/794800001-794850000/794808401-794808500/794808491_16_vrPF_1.jpeg</src> </square_extralarge> <url>http://derkmdt.hyves.nl/fotos/794808491/0/vrPF/</url> <created>1258923192</created> </media> <media> <mediaid>0029f0f9578b37ccf55a0f5ac198ba8c17</mediaid> <userid>00eb4a83be37ec2bad7ea81b7685fd959b</userid> <title>Maffia feestje Maurice & Elsa</title> <description/> <mediatype>image</mediatype> <icon_small> <width>37</width> <height>50</height> <src>http://94.100.122.185/777000001-777050000/777024701-777024800/777024723_1_FSr2_1.jpeg</src> </icon_small> <icon_medium> <width>56</width> <height>75</height> <src>http://94.100.122.185/777000001-777050000/777024701-777024800/777024723_2_FSr2_1.jpeg</src> </icon_medium> <icon_large> <width>90</width> <height>120</height> <src>http://94.100.122.185/777000001-777050000/777024701-777024800/777024723_3_FSr2_1.jpeg</src> </icon_large> <icon_extralarge> <width>150</width> <height>200</height> <src>http://94.100.122.185/777000001-777050000/777024701-777024800/777024723_4_FSr2_1.jpeg</src> </icon_extralarge> <image> <width>375</width> <height>500</height> <src>http://94.100.122.185/777000001-777050000/777024701-777024800/777024723_5_FSr2_1.jpeg</src> </image> <image_fullscreen> <width>525</width> <height>700</height> <src>http://94.100.122.185/777000001-777050000/777024701-777024800/777024723_6_FSr2_1.jpeg</src> </image_fullscreen> <square_large> <width>75</width> <height>75</height> <src>http://94.100.122.185/777000001-777050000/777024701-777024800/777024723_14_FSr2_1.jpeg</src> </square_large> <square_extralarge> <width>120</width> <height>120</height> <src>http://94.100.122.185/777000001-777050000/777024701-777024800/777024723_16_FSr2_1.jpeg</src> </square_extralarge> <url>http://kilian.hyves.nl/fotos/777024723/0/FSr2/</url> <created>1257152000</created> </media> <media> <mediaid>0076ca7ee406a185766f9bf24b35aa20db</mediaid> <userid>0086c0f270b9df851fb5541326db452b2c</userid> <title>Marijn @ Boundary waters, USA</title> <description/> <mediatype>image</mediatype> <icon_small> <width>50</width> <height>37</height> <src>http://94.100.122.87/299100001-299150000/299103601-299103700/299103643_1_rmsx_2.jpeg</src> </icon_small> <icon_medium> <width>75</width> <height>56</height> <src>http://94.100.122.87/299100001-299150000/299103601-299103700/299103643_2_rmsx_2.jpeg</src> </icon_medium> <icon_large> <width>120</width> <height>90</height> <src>http://94.100.122.87/299100001-299150000/299103601-299103700/299103643_3_rmsx_2.jpeg</src> </icon_large> <icon_extralarge> <width>200</width> <height>150</height> <src>http://94.100.122.87/299100001-299150000/299103601-299103700/299103643_4_rmsx_2.jpeg</src> </icon_extralarge> <image> <width>500</width> <height>375</height> <src>http://94.100.122.87/299100001-299150000/299103601-299103700/299103643_5_rmsx_2.jpeg</src> </image> <image_fullscreen> <width>600</width> <height>450</height> <src>http://94.100.122.87/299100001-299150000/299103601-299103700/299103643_6_rmsx_2.jpeg</src> </image_fullscreen> <square_large> <width>75</width> <height>75</height> <src>http://94.100.122.87/299100001-299150000/299103601-299103700/299103643_14_rmsx_2.jpeg</src> </square_large> <square_extralarge> <width>120</width> <height>120</height> <src>http://94.100.122.87/299100001-299150000/299103601-299103700/299103643_16_rmsx_2.jpeg</src> </square_extralarge> <url>http://marijn-s.hyves.nl/fotos/299103643/0/rmsx/</url> <created>1216391756</created> </media> <info> <timestamp_difference>0</timestamp_difference> <running_milliseconds>87</running_milliseconds> <secure_connection>false</secure_connection> </info> </media_get_result> </request> <info> <timestamp_difference>0</timestamp_difference> <running_milliseconds>87</running_milliseconds> <secure_connection>false</secure_connection> </info> </batch_process_result>
