Use of the Max parameter

[darrenparkinson]

Hi Jose,

I think we spoke about this some time ago and I wondered if you'd managed to look into it any further. I thought I'd log it as an issue to continue the conversation.

Essentially the question was regarding the max parameter.

When using the SDK and specifying a Max of 5, it actually returns all items. You mentioned that you believed that was to do with the paging I think. The webex docs say the following:

When requesting a list of resources the max query parameter may be used to control the number of items returned per page. For example, requesting GET /people?displayName=Harold&max=2 tells the API to return only 2 items per page.

And I think you took this to mean that when you specify the max parameter, you are just saying how many you want per page, and you are then returning all pages?

The docs go on to say:

If the requested max query parameter value exceeds what a particular API endpoint allows, only the maximum number of items allowed per page for that endpoint will be returned. A rel="next" link header will be present if another page of results is available.

So I was wondering if you might just return the single page containing the max requested along with the rel="next" header using the RFC5988 standard Cisco mentions:

The Webex APIs implement the RFC5988 (Web Linking) standard for pagination. When requesting a list of resources the response may contain a Link header containing the URLs to the first, next, and previous page.

From memory, you were going to take a look at the python library to see how they handled it. And I think we discussed whether you would just pass the max parameter through or if you would abstract that away to enable an SDK user to specify a larger max size than the teams API and then use the paging internally to return the number the user requested (like the sparky sdk).

Ultimately though, what I'd like to achieve is that when I specify a max of 5, that only 5 results are returned?

Let me know what you think the best way to proceed is.

Speak soon. Thanks again,
D.

[jbogarin]

Thanks for opening this Darren. Let me work on it in the next few days.

[jbogarin]

Darren,

Sorry about the delay and thanks for bringing this back to my attention.

I think there are two ways of doing this:

1. Return only max results and then a way to iterate for next resources.
2. Return all of the results but create a second variable, let’s say limit to skip the page iteration.

I’m not really sure what option do I like the most.

I believe max should be respected because it’s the way to control how many resources you want the API to return at once.

What I’m undecided is about developer experience. If handling the control to the developer of asking for more pages or an extra option to limit to an X amount of results. For example, max = 5 but 15 results.

What do you think?

[darrenparkinson]

I think if you had a max parameter and then just returned that many results, even if it required you to make multiple requests?

[jbogarin]

How would you manage page_size in that case?

[darrenparkinson]

Hmm good question. Either you don’t, and just return as many as they ask for or you implement it separately? Alternatively I guess you could allow the developer to manage it and just pass it through as you say.

[jbogarin]

Ok, let me think about it a bit more during the weekend to see what I come up with.

[jbogarin]

@darrenparkinson I included a paginate = true or paginate = false option. You can use the combination of max and paginate to limit how many items per request and if you want to paginate to obtain more items.