Right. We had a huge discussion on pagination on the OpenStack mailing list back in the day. Most clients simply want to iterate through the collection and as Peter stated using a marker allows you to do this in a non-lossy way. Some of our customers (Rightscale, I think), complained a lot about this issue with our Cloud Servers 1.0 API which used limit offset approach -- which is why we changed it when we went OpenStack. Joe, I hope you reconsider.
Regardless of what approach you decide to take, you might also want to provide "next" links in collections. This allows the client to easily iterate through the list by simply following links. The approach is less error prone and it keeps the client from having to understand your query parameters etc. -jOrGe W. On Jun 11, 2012, at 1:42 PM, Peter Balland wrote: > The problem with page/pagesize parameters for the API is that > retrieving all entities in a non-lossy way requires state storage on > the server (which is not allowed in REST). I understand the > cursor/limit approach is harder for the UI, but these clients already > need to handle problems of sorting, after which page-style pagination > is trivial. > > - Peter > >> From: Joseph Heck <[email protected]> >> Date: Sun, Jun 10, 2012 at 2:08 PM >> Subject: Re: [Netstack] About API v2.0 return value by list_xx >> To: Yong Sheng Gong <[email protected]> >> Cc: [email protected], Jason Kölker <[email protected]>, Jorge >> Williams <[email protected]> >> >> >> Yong - >> >> The V3 keystone API is proposing taking a different tact from the >> "marker+limit" mechanism. Based on the suggestions from the Horizon devs, >> I'm proposing for the next API to enable a "page" and "pagesize" query >> parameter on all the GET requests, with a default pagesize set to 30 to >> specifically enable page forward and page backwards in the user interface. >> >> -joe >> >> >> On Jun 5, 2012, at 3:48 PM, Yong Sheng Gong wrote: >> >> thanks >> I will consider the pagination. >> Yong Sheng Gong >> >> >> -----Jorge Williams <[email protected]> wrote: ----- >> To: Dan Wendlandt <[email protected]> >> From: Jorge Williams <[email protected]> >> Date: 06/06/2012 04:33AM >> Cc: Jason Kölker <[email protected]>, Yong Sheng Gong/China/IBM@IBMCN, >> "<[email protected]>" <[email protected]>, "Mark McLoughlin" >> <[email protected]>, Sumit Naiksatam <[email protected]>, "Somik Behera" >> <[email protected]>, Robert Kukura <[email protected]>, >> "<[email protected]>" <[email protected]>, Erik Carlin >> <[email protected]> >> Subject: Re: About API v2.0 return value by list_xx >> >> There are no formal style guidelines, but collection in compute follow the >> format that you labeled 1.1 below...this is also done by keystone, lbaas and >> others, so I think that's what you should follow. >> >> I also think that you should make sure that you allow for pagination as >> described here: >> >> http://docs.openstack.org/api/openstack-compute/2/content/Paginated_Collections-d1e664.html >> >> -jOrGe W. >> >> >> On Jun 5, 2012, at 2:12 PM, Dan Wendlandt wrote: >> >> Ah, I messed up the order in my last email. You're right, v1.1 maps to what >> nova does, and is what we should follow. >> >> Jorge, I'd still be interested in whether there is a set of style guidelines >> that we should use to guarantee consistency across openstack APIs. >> >> Thanks, >> >> dan >> >> On Tue, Jun 5, 2012 at 12:09 PM, Jason Kölker <[email protected]> wrote: >>> >>> On Tue, 2012-06-05 at 11:21 -0700, Dan Wendlandt wrote: >>>> Adding netstack again... please try to keep it CC'ed :) >>>> >>>> >>>> Yong, great that you're digging up these differences. Would be good >>>> to add an example of a "list" query to the wiki >>>> page: http://wiki.openstack.org/QuantumV2APIIntro >>>> >>>> >>>> I don't have an opinion on one of the options below >>>> being fundamentally better than the other, but a general goal is to >>>> achieve consistency across different openstack APIs. The 2.0 >>>> approach does seem more inline with nova's list server method >>>> >>>> (http://docs.openstack.org/api/openstack-compute/2/content/List_Servers-d1e2078.html#d6e1175), >>>> and such consistency seems like a good thing. >>>> >>>> >>>> Adding Jorge and Erik from Rackspace, as I really think we could >>>> benefit from openstack-wide consistency guidelines with respect to >>>> questions like this (as well as style items like camel-case vs. >>>> underscores vs. dashes). >>>> >>>> >>>> Dan >>>> >>>> >>>> On Tue, Jun 5, 2012 at 10:33 AM, Yong Sheng Gong <[email protected]> >>>> wrote: >>>> >>>> Hi Jason, >>>> I see some differences between returned values 1.1 and 2.0 >>>> api: >>>> 2.0 list network: >>>> { >>>> u 'networks': [{ >>>> u 'network': { >>>> u 'subnets': [], >>>> u 'name': u 'private3', >>>> u 'admin_state_up': True, >>>> u 'op_status': u 'ACTIVE', >>>> u 'id': u '5d7c4e4e-366f-49a4-bec8-92f5610d01d9', >>>> u 'tags': [] >>>> } >>>> }, { >>>> u 'network': { >>>> u 'subnets': [], >>>> u 'name': u 'private3', >>>> u 'admin_state_up': True, >>>> u 'op_status': u 'ACTIVE', >>>> u 'id': u '6bb9b6df- >>>> 4b81-41b5-8743-587d0b6147f9', >>>> u 'tags': [] >>>> } >>>> }] >>>> } >>>> 1.1 is: >>>> { >>>> u 'networks': [{ >>>> u 'subnets': [], >>>> u 'name': u 'private3', >>>> u 'admin_state_up': True, >>>> u 'op_status': u 'ACTYVE', >>>> u 'id': u '5d7c4e4e-366f-49a4-bec8-92f5610d01d9', >>>> u 'tags': [] >>>> } >>>> , { >>>> u 'subnets': [], >>>> u 'name': u 'private3', >>>> A0 u 'admin_state_up': True, >>>> u 'op_status': u 'ACTIVE', >>>> u 'id': u '6bb9b6df- >>>> A 4b81-41b5-8743-587d0b6147f9', >>>> u 'tags': [] >>>> } >>>> ] >>>> } >>>> >>>> Y0 I think we should use 1.1 format. >>> >>> I agree that the list of resources should not be wrapped in the resource >>> object. This slipped by in a refactoring. I updated the merge prop. >>> >>> Happy Hacking! >>> >>> 7-11 >>> >>> >> >> >> >> -- >> ~~~~~~~~~~~~~~~~~~~~~~~~~~~ >> Dan Wendlandt >> Nicira, Inc: www.nicira.com >> twitter: danwendlandt >> ~~~~~~~~~~~~~~~~~~~~~~~~~~~ >> >> >> -- >> Mailing list: https://launchpad.net/~netstack >> Post to : [email protected] >> Unsubscribe : https://launchpad.net/~netstack >> More help : https://help.launchpad.net/ListHelp >> >> >> >> -- >> Mailing list: https://launchpad.net/~netstack >> Post to : [email protected] >> Unsubscribe : https://launchpad.net/~netstack >> More help : https://help.launchpad.net/ListHelp >> >> >> >> >> -- >> ~~~~~~~~~~~~~~~~~~~~~~~~~~~ >> Dan Wendlandt >> Nicira, Inc: www.nicira.com >> twitter: danwendlandt >> ~~~~~~~~~~~~~~~~~~~~~~~~~~~ >> -- Mailing list: https://launchpad.net/~netstack Post to : [email protected] Unsubscribe : https://launchpad.net/~netstack More help : https://help.launchpad.net/ListHelp
