Data-API

Some API calls have resultsets that are potentially very large (my favorite example is users.search(query=amsterdam), which will get you all users in Amsterdam, about 180k results at the moment). Obviously, it would not be good for us, you, or the network to return all those userids; this is the problem solved by pagination.

You can check in the method list which methods are affected by pagination. This are all methods that have the potential to return a number of results not limited by any other means. This are calls like "give me all the X for Y" (all the media for an album, all the gadgets for a user, etc). Not affected are calls that are called by lists of ids: if you are requesting information for a list of 500 userids, we assume you need the information for all 500 userids, so it would make little sense to split the list up in pages. (note that there is a maximum to the number of ids one can supply to any function).

Pagination is controlled by the ha_page and ha_resultsperpage parameters. These parameters are optional to all methods that support pagination, and not allowed with any other method. If omitted, 12 results from page 1 are shown. If the ha_page is larger than the number of pages (which means that ha_page * ha_resultsperpage > totalitems), an empty resultset is shown. If ha_pages <= 0, an error number 33 is returned. Similarly, if ha_resultsperpage is larger than the maximum allowed (currently 100), or <= 0, an error number 34 is returned.

Pagination only makes sense when the result is ordered in some way. The methods that are paginated all have an order similar to the one we use on the site. The exact order is shown in the method list.

Note that all calls you make to the Hyves Api are stateless. This means that there is a possibility that between the calls to retrieve page 1 of gadgets for a user, and page 2, the user has inserted a new gadget on his/her profile. In that case, the last gadget on page 1 is the same as the first gadget on page 2. This behaviour is similar to how pages on the website behave.

<totalresults>73</totalresults>
<totalpages>7</totalpages>
<resultsperpage>12</resultsperpage>
<currentpage>1</currentpage>

The meaning of these keys is explained here (although I suppose it's pretty obvious). These keys are always present when the method is paginated, even when there is only one page of results (or no results at all). Note: if there are no results at all, totalpages will still be 1, namely the empty page you just retrieved.

Pagination adds an info to the info block that is at the bottom of each call.