Pagination pattern (architecture)

Introduction

For web APIs, the "Continuation token" pattern works specially well.

Continuation token (pattern)

The "continuation token" is maybe the only pagination pattern that works well with web APIs.

Reference > https://blog.vermorel.com/journal/2015/5/8/nearly-all-web-apis-get-paging-wrong.html

Highlights:

-Every request has the possibility of returning a continuation token on top of the elements returned when not all elements could be returned in one batch

-Ultimately all elements will be enumerated at least once

-There is not guarantee that the same element won't be enumerated more than once

Example

Let's see an example of a web service operation used for retrieving Learning Units based on a provided search criteria.

/**

 * I finds Learning Units that match the specified search criteria.

 *

 * @param searchCritera DTO with information of the search criteria, and the

 *         'pagingContinuationToken' attribute (on 1st request leave it null, for

 *         subsequent requests provide the pagingContinuationToken returned by the

 *         previous call)

 * @return A DTO with the following information:

 *         -pagingContinuationToken, if informed use it in the subsequent request to

 *             retrieve additional records

 *         -A list of Learning Units that match the specified criteria

 * @throws Whatever

 */

LearningUnitCollectionDto findLearningUnits(final LearningUnitCriteriaDto searchCriteria)

Sample search criteria DTO with 3 attributes for filtering and the 'pagingContinuationToken'

class LearningUnitCriteriaDto{

   /** 'Continuation token' for paging. On 1st request leave it null, for subsequent

    *  requests provide the continuationToken returned by the previous call

    */

   String pagingContinuationToken;

   //

   String langIanaCode; //fitler LUs with specified IANA language code

   String endDateAfterOrOn; //filter LUs after or on specified date (date included)

   String endDateBefore; //filter LUs before specified date (date excluded)

}

Sample results DTO with the list of Learning Units and the 'pagingContinuationToken'

class LearningUnitCollectionDto{

   /** 

    * 'Continuation token' for paging. If informed, use it in the request for additional

    * records

    */

    String pagingContinuationToken;

    List<LearningUnitDto> learningUnits;

}