Description

This document describes the pagination mechanism used in the MGB Api to handle large lists of data returned by some methods. For a complete list of methods that implement pagination inside the MGB Api check the [1] document.

There are two types of paginations inside MGB. The first one is geo pagination which allows retrieving only data that is located in a certain area of a map. This kind of pagination can only be applied to entities that contain GPS location properties (like the PointOfInterest).

The kind of pagination and by far the most used among the API methods is the simple pagination which splits a large list of data in smaller chunks called pages.

Simple pagination mechanism

Pagination parameters

All methods that implement simple pagination take two optional integer parameters:

1.    pageNumber – the number of the page to retrieve from the large chunk of data that the method would return if not paginated. If this parameter is not specified or set to null, it will have the default value of one, which means that the first page will be returned.

2.    pageSize – the number of items per page to be retrieved by the method. If the parameter is not specified or set to null, the default value of 100 will be used. Also, this parameter has an upper limit of 100, meaning that if the consumer specifies a pageSize larger than the upper limit, the upper limit will be used by default.

Paginated reply

On each call to a paginated method, an object will be returned containing two sub objects:

1.    PageInfo – the PageInfo object contains header like information about the returned data. The description of the PageInfo object can be found bellow.

2.    Items – are the actual paginated objects returned by the method. Items is an array of the type of the paginated objects and represents a page.
The PageInfo object contains the following fields:

•    TotalItems – the number total items of the result set. This represents all the items from all the pages or all the items that would be returned if the method wouldn’t have been paginated.

•    ItemsPerPage – the items per page requested in the method call

•    PageNumber – the page number requested in the method call

Examples

Let’s consider calling the GetAllPoisInProfile  method, which returns all the points of interest from a profile.

Calling the method without specifying the pagination parameters would return by default the first page with a maximum of 100 items in it. The method reply would look like:

PagedResultOfPointOfInterest
-    Items [this is the array of PointOfInterest objects representing the call result]
-    PointOfInterest [the first item in the array]
-    PointOfInterest [the second item in the array]
-    ...
-    PointOfInterest[the Nth item in the array]
-    PageInfo [page header data]
-    TotalItems = xxx (the total number of items in the profile
-    ItemsPerPage = 100 (default value for items per page)
-    PageNumber = 1 (default value for page number)

If the method caller wants a specific number of items to be retrieved for every call, the pageSize parameter would have to be set. If the caller wants a specific page number, the pageNumber parameter would have to be set.

For example, the GetAllPoisInProfile method, would have to be called in the following way:

GetAllPoisInProfile([normal method params], 15, 3); // 15 = page size; 3 = page number