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 <he...@me.com> >> 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 <gong...@cn.ibm.com> >> Cc: netstack@lists.launchpad.net, Jason Kölker <ja...@koelker.net>, Jorge >> Williams <jorge.willi...@rackspace.com> >> >> >> 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 <jorge.willi...@rackspace.com> wrote: ----- >> To: Dan Wendlandt <d...@nicira.com> >> From: Jorge Williams <jorge.willi...@rackspace.com> >> Date: 06/06/2012 04:33AM >> Cc: Jason Kölker <ja...@koelker.net>, Yong Sheng Gong/China/IBM@IBMCN, >> "<gkot...@redhat.com>" <gkot...@redhat.com>, "Mark McLoughlin" >> <mar...@redhat.com>, Sumit Naiksatam <snaik...@cisco.com>, "Somik Behera" >> <so...@nicira.com>, Robert Kukura <rkuk...@redhat.com>, >> "<netstack@lists.launchpad.net>" <netstack@lists.launchpad.net>, Erik Carlin >> <erik.car...@rackspace.com> >> 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 <ja...@koelker.net> 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 <gong...@cn.ibm.com> >>>> 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 : netstack@lists.launchpad.net >> Unsubscribe : https://launchpad.net/~netstack >> More help : https://help.launchpad.net/ListHelp >> >> >> >> -- >> Mailing list: https://launchpad.net/~netstack >> Post to : netstack@lists.launchpad.net >> 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 : netstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~netstack More help : https://help.launchpad.net/ListHelp
