[aerogear-dev] Server Side: Paging API with Metadata and Links (was: Re: Paging Demo)

Mon Jan 14 08:41:53 EST 2013

Well, from reading the PR I really think this should be part of the controller - something that decorates the return and sets appropriate headers.

a very high level usage example would be something like this:

public List<Car> findCarsByFoo(Car example) {
    List<Car> cars = // does the magic
    return paginate(cars); // static helper that wraps this list on a lightweight wrapper,
                           // that triggers the behavior
}

Thoughts?

Matzew already put this on our meeting agenda for today, but feel free to send suggestions here :)

-- qmx

On 14/01/2013, at 07:30, Daniel Bevenius <daniel.bevenius at gmail.com> wrote:

> >if we add a dependency on the params into our client library, we pretty much build against a "demo API". 
> There should be no dependencies in the client APIs to these params or headers. This is up the the implementation of the target Route and the params names, the response headers could be anything they user wants. This is just an example where we try to provide a good way of doing this. At least this is my view of it.
> 
> /Dan
> 
> 
> On 14 January 2013 10:28, Matthias Wessendorf <matzew at apache.org> wrote:
> Looking at the PR for the demo ([1]) ,I am a bit surprised that
> classes like "Links.java" or "Metadata.java" are part of the demo
> code.
> 
> I thought that the metadata/header informations on the response, like:
> ```
> AG-Paging-Offset: 1
> AG-Paging-Limit: 4
> AG-Paging-Total: 4
> AG-Links-First: cars?offset=0&limit=4
> AG-Links-Previous: cars?offset=0&limit=4
> AG-Links-Next: cars?offset=2&limit=4
> AG-Links-Last: cars?offset=3&limit=4
> ```
> 
> are applied by the framework. Of course, the "cars" in there is app
> specific, but this information could be read out of the actual route
> (/cars).
> 
> Not sure, but... if all the time we (end user) needs to (re)impl.
> these things... it could be a bit annoying.
> 
> 
> IMO the problem would be:
> - if we add a dependency on the params into our client libraries, we
> pretty much build against a "demo API". Which is odd...
> I thought these "metadata details" are offered by the framework.
> 
> -M
> 
> [1] https://github.com/aerogear/aerogear-controller-demo/pull/19
> 
> On Sun, Jan 13, 2013 at 12:09 PM, Daniel Bevenius
> <daniel.bevenius at gmail.com> wrote:
> > I've updated the demo and think I've included all the requests.
> > * Pre-populate the database upon deployment of demo.
> > * Use 'offset/limit' instead of 'page/perPage'.
> > * Use 'AG-' prefix for headers.
> >
> > Let me know if you are missing anything, or would like something done in a
> > different way.
> >
> > Use case
> >
> > The example is using /cars as the resource to interact with.
> >
> > The following route has been added to the demo:
> >
> > route()
> >       .from("/cars")
> >       .on(RequestMethod.GET)
> >       .produces(MediaType.JSON)
> >       .to(Cars.class).get(param("offset", "0"), param("limit", "-1"));
> >
> > From this we can see that there are two optional parameters, offset and
> > limit. If these are not specified all cars will be returned.
> >
> > Getting a page of Cars
> >
> > curl -i --header "Accept: application/json"
> > "http://controllerdemo-danbev.rhcloud.com/aerogear-controller-demo/cars?offset=0&limit=4"
> >
> > The request will return:
> >
> > HTTP/1.1 200 OK
> > Content-Type: application/json;charset=UTF-8
> > Content-Length: 160
> > AG-Paging-Offset: 0
> > AG-Paging-Limit: 4
> > AG-Paging-Total: 4
> > AG-Links-Next: cars?offset=1&limit=4
> > AG-Links-Last: cars?offset=3&limit=4
> > [
> >   {"color":"Green","brand":"Audi","id":1},
> >   {"color":"White","brand":"Audi","id":2},
> >   {"color":"Black","brand":"Audi","id":3},
> >   {"color":"Black","brand":"BMW","id":4}
> > ]
> >
> > Getting the next page of Cars
> >
> > To get the next page you can follow the next link:
> >
> > curl -i --header "Accept: application/json"
> > "http://controllerdemo-danbev.rhcloud.com/aerogear-controller-demo/cars?offset=1&limit=4"
> >
> > HTTP/1.1 200 OK
> > Content-Type: application/json;charset=UTF-8
> > Content-Length: 166
> > AG-Paging-Offset: 1
> > AG-Paging-Limit: 4
> > AG-Paging-Total: 4
> > AG-Links-First: cars?offset=0&limit=4
> > AG-Links-Previous: cars?offset=0&limit=4
> > AG-Links-Next: cars?offset=2&limit=4
> > AG-Links-Last: cars?offset=3&limit=4
> > [
> >    {"color":"Green","brand":"BMW","id":5},
> >    {"color":"Red","brand":"Ferrari","id":6},
> >    {"color":"White","brand":"Ferrari","id":7},
> >    {"color":"Pink","brand":"Ferrari","id":8}
> > ]
> >
> > Get all Cars
> >
> > curl -i --header "Accept: application/json"
> > "http://controllerdemo-danbev.rhcloud.com/aerogear-controller-demo/cars"
> >
> > This request will return:
> >
> > [
> >    {"color":"Green","brand":"Audi","id":1},
> >    {"color":"White","brand":"Audi","id":2},
> >    {"color":"Black","brand":"Audi","id":3},
> >    {"color":"Black","brand":"BMW","id":4},
> >    {"color":"Green","brand":"BMW","id":5},
> >    {"color":"Red","brand":"Ferrari","id":6},
> >    {"color":"White","brand":"Ferrari","id":7},
> >    {"color":"Pink","brand":"Ferrari","id":8},
> >    {"color":"White","brand":"Golf","id":15},
> >    {"color":"Brown","brand":"Lada","id":16},
> >    {"color":"Orange","brand":"Mazda","id":14},
> >    {"color":"Pink","brand":"Mini","id":13},
> >    {"color":"Gray","brand":"Nissan","id":11},
> >    {"color":"Yello","brand":"Opel","id":10},
> >    {"color":"Blue","brand":"Scoda","id":9},
> >    {"color":"Red","brand":"Volvo","id":12}
> > ]
> >
> > Get a single Car
> >
> > curl -i --header "Accept: application/json"
> > "http://controllerdemo-danbev.rhcloud.com/aerogear-controller-demo/cars/1"
> >
> > The request will return:
> >
> > {"color":"Green","brand":"Audi","id":1}
> >
> >
> >
> > On 12 January 2013 11:08, Daniel Bevenius <daniel.bevenius at gmail.com> wrote:
> >>
> >> Great, lets go with 'AG-' prefix then.
> >>
> >>
> >>
> >>
> >> On 11 January 2013 18:24, Douglas Campos <qmx at qmx.me> wrote:
> >>>
> >>>
> >>> On 11/01/2013, at 15:10, Kris Borchers <kris at redhat.com> wrote:
> >>> > I guess what I meant is I'm not specifically +1 for X- prefix but just
> >>> > some sort of prefix in general. It just makes it easier for devs when
> >>> > looking through headers to see what is being sent. Even something like AG-
> >>> > or AeroGear- would be better IMO than no prefix.
> >>>
> >>> d'oh, +1 - thought I've typed it…
> >>>
> >>> AG- looks nicer - less bandwidth ;)
> >>>
> >>> -- qmx
> >>> _______________________________________________
> >>> aerogear-dev mailing list
> >>> aerogear-dev at lists.jboss.org
> >>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
> >>
> >>
> >
> >
> > _______________________________________________
> > aerogear-dev mailing list
> > aerogear-dev at lists.jboss.org
> > https://lists.jboss.org/mailman/listinfo/aerogear-dev
> >
> 
> 
> 
> --
> Matthias Wessendorf
> 
> blog: http://matthiaswessendorf.wordpress.com/
> sessions: http://www.slideshare.net/mwessendorf
> twitter: http://twitter.com/mwessendorf
> 
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev
> 
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev