[katello-devel] API v2 - proposed changes in routes

Dmitri Dolguikh dmitri at redhat.com
Tue Mar 5 15:49:44 UTC 2013


On 05/03/13 02:46 PM, Eric D Helms wrote:
>
>
>
> On Tue, Mar 5, 2013 at 9:31 AM, Dmitri Dolguikh <dmitri at redhat.com 
> <mailto:dmitri at redhat.com>> wrote:
>
>     On 05/03/13 01:29 PM, Eric D Helms wrote:
>
>         On #2, if one of our core operating principles is that nearly
>         everything is scoped based on an organization, why would we
>         want to abstract that away and not make it explicit as part of
>         resource look-up?  Given that a design goal of RESTful APIs is
>         to be predictable, I would think the form that includes
>         organization at the trunk of the route is more predictable and
>         mimics how resources are structured.
>
>         On changes to JSON format, I would like to make the request
>         that there be thought put into API "paging".  I am starting to
>         work on using the API for some UI components and adding our
>         Elasticsearch infrastructure to these API calls.  This
>         typically involves requesting a chunk of resources (say 25 for
>         example) and then requesting the next 25 as the user demands
>         them.  As well, being able to look at the returned data to
>         know the total number of records even though I am only getting
>         say 26-50 with that particular call.
>
>
>     Hmm, wouldn't paging be better expressed as a url parameter (it is
>     in essence a filter after all):
>
>      /organizations/?from=10&to=20
>
>     Total number of records in the collection would come in json though.
>
>
> It would still be expressed as URL parameters but the collection 
> object should also contain this.  Consider you are working with just 
> the collection, you want to know what chunk you are dealing with 
> without having to parse out the URL.  This is a common pattern from my 
> experience as well, e.g.  Possibly even including what generated this 
> particular chunk.  But at a minimum:
>
> {
>     total: 365,
>     offset: 25,
>     limit: 25
>
>     items : [{
>
>     }]
> }

Hmm. I actually don't see the need for the offset and limit *inside* the 
collection:
  - You don't need to parse the url, as you have "offset" and "limit" 
values in the scope from which the collection retrieval happened (and 
you can use them directly)
  - This introduces iteration state into the collection, which turns it 
into a cursor/iterator style object (which it isn't). You *could* 
introduce a cursor resource if you wanted to keep track of paging on the 
server-side, but really
  - You should wrap collection paging into an iterator-style helper on 
the client/web-ui-controller.

-d
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/katello-devel/attachments/20130305/fc3a577e/attachment.htm>


More information about the katello-devel mailing list