Understanding Pagesize and Offset

Often APIs which potentially return a long list of results, implement what is called paging. Basically it means that the long list of results is divided up into smaller pages which can be retrieved one by one, or that you provide the number of results you would like in one page and where in the list to start.

Pagesize is the number of results you would like the API to return to you. Most APIs which implement paging have a default pagesize so if you call the API without providing a pagesize, it will return some set of reasonable number of results. You can provide a pagesize smaller or higher than the default as well, though most APIs will have an upper limit to pagesize. So for example, if the API could return thousands of results, it may implement a default pagesize of 100 results. If you call the API without providing a pagesize, you’ll get 100 results. You could call the API with a pagesize of 5 to get only 5 results or 300 to get 300 results. But probably not with a pagesize of 1,000,000.

Offset is where in the list you want to start retrieving results. Since pagesize can vary, where in the list of results you need to start retrieving the next set of results also can vary. The first time you call an API, you may provide a pagesize of 10. After you retrieve the first ten results, you may want to retrieve the next ten, so you would call the API with a pagesize of 10 and an offset of 10. This would get you results 11 through 20. The next API call you might provide a pagesize of 10 and an offset of 20, and so on.

Often when an API implements paging, it will also provide you the total number of possible results, so you can know when you have retrieved them all and can stop call the API.