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

[Matthias Wessendorf]

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