Special request, we've settled on limit/offset after a long discussion - let's try
to use those to stay consistent across all platforms ;)
-- qmx
On 11/01/2013, at 14:11, Daniel Bevenius <daniel.bevenius(a)gmail.com> wrote:
I've updated the demo on openshift now. Let me know if you find
an issues with it. I was not sure about the total metadata, do we want the total number of
pages, or the total number of entries (we can do both). I've gone with total number of
pages for the time being:
Getting a page of Cars
URL="http://controllerdemo-danbev.rhcloud.com/aerogear-controller-de...
curl -i --header
"Accept: application/json" "$URL/cars?page=0&perPage=4"
The request will return:
HTTP/1.1 200 OK
MetaData-TotalPages: 3
MetaData-PerPage: 4
MetaData-Page: 0
Links-Next: cars?page=1&perPage=4
Links-Last: cars?page=2&perPage=4
Content-Type: application/json;charset=UTF-8
Content-Length: 161
[
{"color":"Black","brand":"BMW","id":1},
{"color":"Red","brand":"Ferrari","id":2},
{"color":"Blue","brand":"Skoda","id":3},
{"color":"Green","brand":"Audi","id":4}
]
Getting the next page of Cars
To get the next page you can follow the next link:
URL="http://controllerdemo-danbev.rhcloud.com/aerogear-controller-de...
curl -i --header
"Accept: application/json" "$URL/cars?page=1&perPage=4"
HTTP/1.1 200 OK
MetaData-TotalPages: 3
MetaData-PerPage: 4
MetaData-Page: 1
Links-First: cars?page=0&perPage=4
Links-Previous: cars?page=0&perPage=4
Links-Next: cars?page=2&perPage=4
Links-Last: cars?page=2&perPage=4
Content-Type: application/json;charset=UTF-8
Content-Length: 160
[
{"color":"Yello","brand":"Opel","id":5},
{"color":"Pink","brand":"Mini","id":6},
{"color":"Gray","brand":"Nissan","id":7},
{"color":"Red","brand":"Volvo","id":8}
]
On 11 January 2013 13:45, Daniel Bevenius <daniel.bevenius(a)gmail.com> wrote:
>If you use headers they should start with X-My-Header. So it is separated of the
standard headers and marked as extension.
Please correct me if I'm wrong, but I thought that the "X-" header prefix
were deprecated (
http://tools.ietf.org/html/rfc6648) and not advised. But this is all up
the to implementor of the Route and you can name then what ever you like.
Thanks,
/Dan
On 11 January 2013 13:39, Kris Borchers <kris(a)redhat.com> wrote:
On Jan 11, 2013, at 6:36 AM, Daniel Manzke <daniel.manzke(a)googlemail.com> wrote:
> I have to say I like all proposals. Having access to the informations in the json is
the facebook way. It is easy to build an graph explorer. No need to get low level.
>
> On the other hand, if you want to be more consistent, I would go the way of the last
proposal. I think this is in a more common sense to http. Think about the Range header,
which is used for downloading.
> You specify what part you want to have.
>
> If you use headers they should start with X-My-Header. So it is separated of the
standard headers and marked as extension.
+1 on "X-" prefix.
>
> Last but not least, I always like the Content-Negotiation way, where you can have a
url like ".../download/myfile.pdf" which would translate to only accept pdfs
(@Produces). It can also be used for sending xml instead of json. (default with json
"/cars" and specific would be "/cars.json" or "/cars.xml".
What is this XML you speak of? (Sorry, ignore the comments from the JavaScript guy :P)
>
>
> Bye,
> Daniel
>
>
> 2013/1/11 Kris Borchers <kris(a)redhat.com>
>
> On Jan 11, 2013, at 5:01 AM, Daniel Bevenius <daniel.bevenius(a)gmail.com>
wrote:
>
>> Hey Kris,
>>
>> been thinking about your reply regarding the inconsistency of the returned data.
I think it looks a little odd to have the 'cars' property returned when requesting
a single car.
>> What do you all think of this as a suggestion below?
>
> I'm sorry, I misread that e-mail and thought these were both requests to the
/cars endpoint and the data returned was formatted differently based on the data length.
What you have makes sense so disregard what I said.
>
>>
>> As you can see we now return HTTP Headers and also the object returned is either
an array of cars, or just a single object if you only request a single car.
>>
>> Getting a page of Cars
>>
URL="http://controllerdemo-danbev.rhcloud.com/aerogear-controller-de...
>>
>> curl -i --header
>> "Accept: application/json" "$URL/cars?page=0&perPage=4"
>> The request will return:
>>
>> HTTP/1.1 200 OK
>> Link-Previous: cars?page=0&page=4
> IMO, if we are on the first page the Link-Previous header should be empty since there
is no previous page. That will make it easier for people building the UI to know if they
should show a previous link, etc. Also, you can't have two parameters with the same
name, should that actually be page=0&perPage=4?
>> Link-First: cars?page=0&page=4
> Same thing, page/perPage?
>
>> MetaData-PerPage: 4
>> MetaData-Page: 0
>> Link-Next: cars?page=1&page=4
> Same as previous, if we are on the last page, there should not be a value for
Link-Next. Also, as above, page/perPage?
>
>> Content-Type: application/json;charset=UTF-8
>> Content-Length: 161
>> [
>>
>>
>>
{"color":"Black","brand":"BMW","id":1},
>>
>>
>>
{"color":"Red","brand":"Ferrari","id":2},
>>
>>
>>
{"color":"Blue","brand":"Skoda","id":3},
>>
>>
>>
{"color":"Green","brand":"Audi","id":4}
>> ]
>>
>> Get a single Car
>>
>>
URL="http://controllerdemo-danbev.rhcloud.com/aerogear-controller-de...
>>
>> curl -i --header
>> "Accept: application/json" "$URL/cars/1"
>> The request will return:
>>
>>
{"color":"Black","brand":"BMW","id":1}
>>
>>
>> On 10 January 2013 20:00, Daniel Bevenius <daniel.bevenius(a)gmail.com>
wrote:
>> Summers brought up a good point today on IRC which I've forgot to mention.
We've said that it will be possible to pass the page parameters as HTTP Headers and
this is still the plan. But the demo is using the lastest from upstream and support for
passing headers to the client is not there yet. I hope to have this working shortly though
and I'll post back with information as soon as possible, tomorrow or Monday at the
latest.
>>
>>
>>
>>
>> On 10 January 2013 15:32, Daniel Bevenius <daniel.bevenius(a)gmail.com>
wrote:
>> >I know it's just a demo but I think making that JSON format consistent so
that the car data is always in an array under the "cars" key would be better.
>> Good point. I'll change this so that there is always a "cars' key.
>>
>>
>> On 10 January 2013 15:13, Kris Borchers <kris(a)redhat.com> wrote:
>>
>> On Jan 10, 2013, at 3:02 AM, Daniel Bevenius <daniel.bevenius(a)gmail.com>
wrote:
>>
>>> We talked about paging yesterday on IRC, and it was decided to add a paging
example to aerogear-controller-demo. What follows is an example to kick of further
discussion about what the example should look like.
>>>
>>> AeroGear Controller Demo Paging Route
>>> This page discusses AEROGEAR-795 which is about adding an example to
aerogear-controller-demo to demonstrate paging support so that the client libraries
(Android, JavaScript, and iOS) can be tested against it.
>>>
>>> This is only a suggestion and the implementation and the names of the query
parameters can all be changed.
>>>
>>> Use case
>>>
>>> The example is using cars as the resource to interact with. To be able to
query we need something to query, so lets start by adding some cars by posting.
>>>
>>> Adding Cars
>>>
>>>
URL="http://controllerdemo-danbev.rhcloud.com/aerogear-controller-de...
>>>
>>>
>>> curl -i --header
>>> "Accept: application/json" -H "Content-type:
application/x-www-form-urlencoded" --data
"car.color=Black&car.brand=BMW" -X POST "$URL/cars"
>>>
>>> curl -i --header
>>> "Accept: application/json" -H "Content-type:
application/x-www-form-urlencoded" --data
"car.color=Red&car.brand=Ferrari" -X POST "$URL/cars"
>>>
>>> curl -i --header
>>> "Accept: application/json" -H "Content-type:
application/x-www-form-urlencoded" --data
"car.color=Blue&car.brand=Skoda" -X POST "$URL/cars"
>>>
>>> curl -i --header
>>> "Accept: application/json" -H "Content-type:
application/x-www-form-urlencoded" --data
"car.color=Green&car.brand=Audi" -X POST "$URL/cars"
>>>
>>> curl -i --header
>>> "Accept: application/json" -H "Content-type:
application/x-www-form-urlencoded" --data
"car.color=Yello&car.brand=Opel" -X POST "$URL/cars"
>>>
>>> curl -i --header
>>> "Accept: application/json" -H "Content-type:
application/x-www-form-urlencoded" --data
"car.color=Pink&car.brand=Mini" -X POST "$URL/cars"
>>>
>>> curl -i --header
>>> "Accept: application/json" -H "Content-type:
application/x-www-form-urlencoded" --data
"car.color=Gray&car.brand=Nissan" -X POST "$URL/cars"
>>>
>>> curl -i --header
>>> "Accept: application/json" -H "Content-type:
application/x-www-form-urlencoded" --data
"car.color=Red&car.brand=Volvo" -X POST "$URL/cars"
>>>
>>> curl -i --header
>>> "Accept: application/json" -H "Content-type:
application/x-www-form-urlencoded" --data
"car.color=Blue&car.brand=Saab" -X POST "$URL/cars"
>>>
>>> curl -i --header
>>> "Accept: application/json" -H "Content-type:
application/x-www-form-urlencoded" --data
"car.color=Black&car.brand=Mazda" -X POST "$URL/cars"
>>>
>>> curl -i --header
>>> "Accept: application/json" -H "Content-type:
application/x-www-form-urlencoded" --data
"car.color=Yello&car.brand=Golf" -X POST "$URL/cars"
>>> The example uses an in-memory database so the data will be cleared upon
redployment/restart of the server. So you only need to populate/post when you've
restared or redployed.
>>>
>>> With the cars in place, we can now issue GET requests with paging query
parameters. The following route has been added to the demo:
>>>
>>> route()
>>>
>>>
>>> .from("/cars")
>>>
>>>
>>> .on(RequestMethod.GET)
>>>
>>>
>>> .produces(MediaType.JSON.toString())
>>>
>>>
>>> .to(Cars.class).get(param("page", "0"),
param("perPage", "-1"));
>>> From this we can see that there are two optional parameters, page and
perPage. If these are not specified all cars will be returned.
>>>
>>> Getting a page of Cars
>>>
>>>
URL="http://controllerdemo-danbev.rhcloud.com/aerogear-controller-de...
>>>
>>> curl -i --header
>>> "Accept: application/json"
"$URL/cars?page=0&perPage=4"
>>> The request will return:
>>>
>>> {
>>>
>>>
>>> "metadata":{"page":0,"perPage":4},
>>>
>>>
>>> "cars":[
>>>
>>>
>>>
{"color":"Black","brand":"BMW","id":1},
>>>
>>>
>>>
{"color":"Red","brand":"Ferrari","id":2},
>>>
>>>
>>>
{"color":"Blue","brand":"Skoda","id":3},
>>>
>>>
>>>
{"color":"Green","brand":"Audi","id":4}
>>>
>>>
>>> ],
>>>
>>>
>>> "links":{
>>>
>>>
>>> "first":"cars?page=0&page=4",
>>>
>>>
>>> "previous":"cars?page=0&page=4",
>>>
>>>
>>> "next":"cars?page=1&page=4"
>>>
>>>
>>> }
>>> }
>>> Getting the next page of Cars
>>>
>>> To get the next page you can follow the next link:
>>>
>>>
URL="http://controllerdemo-danbev.rhcloud.com/aerogear-controller-de...
>>>
>>> curl -i --header
>>> "Accept: application/json"
"$URL/cars?page=1&perPage=4"
>>> {
>>>
>>>
>>> "metadata":{"page":1,"perPage":4},
>>>
>>>
>>> "cars":[
>>>
>>>
>>>
{"color":"Yello","brand":"Opel","id":5},
>>>
>>>
>>>
{"color":"Pink","brand":"Mini","id":6},
>>>
>>>
>>>
{"color":"Gray","brand":"Nissan","id":7},
>>>
>>>
>>>
{"color":"Red","brand":"Volvo","id":8}
>>>
>>>
>>> ],
>>>
>>>
>>> "links":{
>>>
>>>
>>> "first":"cars?page=0&page=4",
>>>
>>>
>>> "previous":"cars?page=0&page=4",
>>>
>>>
>>> "next":"cars?page=2&page=4"
>>>
>>>
>>> }
>>> }
>>> Get all Cars
>>>
>>>
URL="http://controllerdemo-danbev.rhcloud.com/aerogear-controller-de...
>>>
>>> curl -i --header
>>> "Accept: application/json" "$URL/cars"
>>> Get a single Car
>>>
>>>
URL="http://controllerdemo-danbev.rhcloud.com/aerogear-controller-de...
>>>
>>> curl -i --header
>>> "Accept: application/json" "$URL/cars/1"
>>> The request will return:
>>>
>>>
{"color":"Black","brand":"BMW","id":1}
>>
>> Hmmm, the data returned should be consistent, right? Whether paging parameters
are supplied or not, the structure of the JSON to access the car info should be the same.
It's fine to leave out the metadata and links when they're not needed I guess but
to access the car info, currently you have:
>>
>> Not Paged:
{"color":"Black","brand":"BMW","id":1}
>> Paged:
{"cars":[{"color":"Black","brand":"BMW","id":1},…]}
>>
>> I know it's just a demo but I think making that JSON format consistent so
that the car data is always in an array under the "cars" key would be better.
>>> Again, anything here can be changed, the name of the query parameters, the
implementation, and what is returned.
>>>
>>> Reference:
>>>
>>> • Paging Support in AeroGear Controller
>>> _______________________________________________
>>> aerogear-dev mailing list
>>> aerogear-dev(a)lists.jboss.org
>>>
https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>
>>
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev(a)lists.jboss.org
>>
https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>
>>
>>
>>
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev(a)lists.jboss.org
>>
https://lists.jboss.org/mailman/listinfo/aerogear-dev
>
>
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev(a)lists.jboss.org
>
https://lists.jboss.org/mailman/listinfo/aerogear-dev
>
>
>
>
> --
> Viele Grüße/Best Regards
>
> Daniel Manzke
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev(a)lists.jboss.org
>
https://lists.jboss.org/mailman/listinfo/aerogear-dev
_______________________________________________
aerogear-dev mailing list
aerogear-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev
_______________________________________________
aerogear-dev mailing list
aerogear-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev