AeroGear Controller Demo Paging Route

gistfile1.md

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.

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(JSON)
      .to(Cars.class).findCarsBy(param(PaginationInfo.class), param("color"));

The target endpoint method is the annotated and this is where the actual pagination can be configured:

@Paginated 
public List<Car> findCarsBy(PaginationInfo paginationInfo, String color) {
    return getCars(paginationInfo.getOffset(), color, paginationInfo.getLimit());
}

PaginationInfo is used to avoid having to add the params for 'offset' and 'limit' which would have otherwise been required:

.to(Cars.class).findCarsBy(param("offset"), param("limit"), param("color"));

Also, imaging that you need to specify default values and it can get pretty messy. So, instead the PaginationInfo type is used and it will be populated with the request values which are the available to the target method.

Now, by default Web Linking is used to provide links to the next and previous pages as appropriate. Web Linking can be disabled in favor of using a perhaps simpler option of custom headers.

For example, to specify that that you want to use different names of the query parameters (default offset and limit), and that you'd like to use custom headers instead of Web Linking you could add the following values to the annotation:

@Paginated (webLinking = false, 
            customHeadersPrefix = "MYAPP-", 
            offsetParamName = "myoffset", defaultLimit = 5, 
            limitParamName = "mylimit", defaultOffset = 0)
public List<Car> findCarsByCustomHeaders(PaginationInfo paginationInfo, String color) {
    return getCars(paginationInfo.getOffset(), color, paginationInfo.getLimit());
}

The examples below are using Web Linking, but if you'd like to see what custom headers look like then you can simply replace cars with cars-custom.

Getting a page of Cars

curl -i --header "Accept: application/json" "http://controller-aerogear.rhcloud.com/aerogear-controller-demo/cars?offset=0&color=red&limit=5"

The request will return:

HTTP/1.1 200 OK
Date: Tue, 22 Jan 2013 12:10:37 GMT
Server: Apache-Coyote/1.1
Link: <http://controller-aerogear.rhcloud.com/aerogear-controller-demo/cars?offset=5&color=red&limit=5>; rel="next"
Content-Type: application/json;charset=UTF-8
Content-Length: 194

[
      {"color":"red","brand":"Audi","id":6},
      {"color":"red","brand":"BMW","id":13},
      {"color":"red","brand":"Fiat","id":20},
      {"color":"red","brand":"Golf","id":27},
      {"color":"red","brand":"Lada","id":34}
]

Getting the next page of Cars

To get the next page you can follow the next link:

curl -i --header "Accept: application/json" "http://controller-aerogear.rhcloud.com/aerogear-controller-demo/cars?offset=5&color=red&limit=5"

HTTP/1.1 200 OK
Date: Tue, 22 Jan 2013 12:10:37 GMT
Server: Apache-Coyote/1.1
Link: <http://controller-aerogear.rhcloud.com/aerogear-controller-demo/cars?offset=0&color=red&limit=5>; rel="previous",
<http://controller-aerogear.rhcloud.com/aerogear-controller-demo/cars?offset=10&color=red&limit=5>; rel="next"
Content-Type: application/json;charset=UTF-8
Content-Length: 200

[
      {"color":"red","brand":"Mazda","id":41},
      {"color":"red","brand":"Mini","id":48},
      {"color":"red","brand":"Nissan","id":55},
      {"color":"red","brand":"Opel","id":62},
      {"color":"red","brand":"Scoda","id":69}
]

"Paging" beyond the last page of Cars

curl -i --header "Accept: application/json" "http://controller-aerogear.rhcloud.com/aerogear-controller-demo/cars?offset=15&color=red&limit=5"

HTTP/1.1 200 OK
Link: <http://controller-aerogear.rhcloud.com/aerogear-controller-demo/cars?offset=10&color=red&limit=5>; rel="previous"
Content-Type: application/json;charset=UTF-8
Content-Length: 2

[]

Get a single Car

curl -i --header "Accept: application/json" "http://controller-aerogear.rhcloud.com/aerogear-controller-demo/cars/1"

The request will return:

{"color":"Green","brand":"Audi","id":1}

Trying to get a Car that does not exist

curl -i --header "Accept: application/json" "http://controller-aerogear.rhcloud.com/aerogear-controller-demo/cars/135"

The request will return:

HTTP/1.1 404 Not Found
Date: Sun, 20 Jan 2013 14:17:05 GMT
Content-Length: 44

{"error":"Could not find a Car with id=135"}

Reference:

• [Error Message in AeroGear Controller Demo] (https://gist.github.com/4585554)
• [Paging Support in AeroGear Controller] (https://gist.github.com/4147473)