REST: Best practice for pagination?

Software Platform
1

From our 2015-06-17 Design Forum discussion, we would like to agree on the pragmatic best practice for handling pagination within REST+JavaScript.

Although RFC 5988 includes a link header for pagination, the convention in our REST services is to use a form:

{
  "results": [ ... ],
  "links": [
    "prev": "https://example.com/openmrs/...",
    "next": "https://example.com/openmrs/..."
  ]
}

But what should the code for the client look like? Most folks are using AngularJS for the front-end, so we are most interested in solutions that work well with Angular. For example, the UI Commons module uses promises to return results.

We know that pagination is not fully implemented & consistent across resources at this time; however, our hope is to decide on best practice and then prioritize implementing it across all resources.

Some thoughts from our design discussion:

  • Don’t load all results by default. We don’t want to encourage unnecessarily loading potentially thousands of resources; if someone needs everything, they can specifically ask for everything or loop until they get it all.

  • Should the count be included in the REST response?

  • A generic JavaScript solution compatible with Angular would be nice; however, writing asynchronous code that integrates properly with Angular may be complicated and could be deferred until needed.

For example, in the simplest interaction a client should be able to ask for resources and continue to ask for more until it reaches the end:

results = resource.load(); /* load a page of resources */
results.loadMore(3); /* load up to 3 more pages */
results.loadAll(); /* load all resources */

Thoughts? What code would you expect/prefer to load paginated resources from the server?