Pagination in AeroGear

gistfile1.md

Pagination RESTFul API on AeroGear Controller

This document describes pagination in AeroGear. It defines the metadata passed between the client and server.

Parameters

• offset
  The offset of the first element that should be included in the returned collection. Default value is 0.
• limit
  The number of elements that should be returned. Default value is 10
• total
  The total number of elements available.

Metadata

Information about the pagination parameters, and url links to the first, previous, next, and last need to be passed from the server to the clients. There are several options available here:

• Information is passed as HTTP Response Headers
• Information is passed in the body of the Response along with the data

HTTP Response Headers

Paging parameters

• AG-Paging-Total:
  The total number of elements available is passed back to the calling client for every request. This is done as this number might change.

Links

• AG-Links-First: cars?offset=0&limit=10
  The url to the first set of items.
• AG-Links-Previous: cars?offset=10&limit=10
  The url to the previous set of items
• AG-Links-Next: cars?offset=20&limit=10
  The url to the next set of items
• AG-Links-Last: cars?offset=900&limit=10
  The url to the last set of items

Alternatively use Web Linking:

• Link:

<https://localhost/demo/cars?offset=0&limit=10>; rel="first",
<https://localhost/demo/cars?offset=10&limit=10>; rel="previous",  
<https://localhost/demo/cars?offset=30&limit=10>; rel="next",  
<https://localhost/demo/cars?offset=90&limit=10>; rel="last"  

I think the 'web linking' reads a bit odd - but it's a standard (RFC 5988), so I am in fav. of using that syntax for decorating the response