Pagination

Many API calls can potentially return a very large number of results. In order to not overwhelm either the client or the EMS servers, the number of results returned per call of the API is limited to a maximum of the EMS REST Proxy's configured proxy.page_limit. All results for a given API call can then be paged through one page at a time by the client.

API calls that support pagination have cursor and limit query parameters. The limit query parameter can be used if a page limit smaller than the default specified by the EMS REST Proxy's proxy.page_limit option is desired. The cursor parameter is not used during the initial API request, but is used on subsequent requests to page through the list of results. Each response from an API that supports pagination will feature a set of pagination cursors - "first", "prev", "self", "next", and "last" - that can be used to page through the results by setting the cursor query parameter to the value of one of these cursor fields. For example, an initial call to GET /users like this:

curl -kvs -c cookies.txt -b cookies.txt 'https://localhost:8080/users?limit=1'

might return:

{
    "errors": [],
    "first": "CrVZoN1lGqbB_QPPjn_AHbaZ-a0mcLdRM8iffltjYMP0CEPy",
    "last": "DnYGmWc-6vnWeWIcjVm_OUhi6bfTryK2ShMgSgOwx96N7rQL",
    "next": "DXacmsJgwuGspIulkU9lplPlSdnX13-PifHvJA3SNIoHX990",
    "prev": "",
    "self": "CrVZoN1lGqbB_QPPjn_AHbaZ-a0mcLdRM8iffltjYMP0CEPy",
    "users": [
        {
            "description": "Route Server",
            "external": false,
            "name": "EMS-SERVER2",
            "server_group": "group1",
            "server_role": "srv1"
        }
    ]
}

Cursors are opaque (they are not user readable) but are comparable within the set of cursors returned in a single response (but they are not comparable between responses). Note in the above example response that:

• Since this is the very first page of results, the "prev" cursor is empty (there is no previous page)
• the "first" and "self" cursors are identical - because the first page of results is this current page.

To retrieve the next user, call GET /users again with the cursor query parameter set to the value of the returned "next" cursor:

curl -kvs -c cookies.txt -b cookies.txt 'https://localhost:8080/users?cursor=DXacmsJgwuGspIulkU9lplPlSdnX13-PifHvJA3SNIoHX990'

The result might look like:

{
    "errors": [],
    "first": "D2Bh-SYA_xrAD6S6JQiMPboDhdZneVzG-6Mb5dxxmieJ75nr",
    "last": "EvS7-sMF8C0Q4hjDmuMCsibfMa1D7v3euWt3cBATzaCFane6",
    "next": "EvS7-sMF8C0Q4hjDmuMCsibfMa1D7v3euWt3cBATzaCFane6",
    "prev": "D2Bh-SYA_xrAD6S6JQiMPboDhdZneVzG-6Mb5dxxmieJ75nr",
    "self": "ESjcLs1jT--N9ufYkEib8i0c0H-LuLt7YmrnfsBcMLCeB-XC",
    "users": [
        {
            "description": "Main Server",
            "external": false,
            "name": "EMS-SERVER",
            "server_group": "group1",
            "server_role": "srv1"
        }
    ]
}

This time, notice that "first" and "prev" cursors are the same, indicating that the previous page was also the first page in the results. The "self" cursor does not match either the "first" or the "last" cursor values, indicating that this page is somewhere in the middle of the results. Notice also that the "next" and "last" cursors are the same - indicating that the next page of results will be the last page. So let's request the "next" page again:

curl -kvs -c cookies.txt -b cookies.txt 'https://localhost:8080/users?cursor=EvS7-sMF8C0Q4hjDmuMCsibfMa1D7v3euWt3cBATzaCFane6'

and we get back:

{
    "errors": [],
    "first": "FNzIURy9V-kUg3NRKo5Z2oyRc8872gpOVrs2hHpHKErAEmXQ",
    "last": "Fq_DP3jPGrqfjorOmVg4h5ZJU6W4Ip3gcD82BTb9UGP2zz96",
    "next": "",
    "prev": "FSh3V3_sbbLJuL8e5SzSO5ziKq_cb0eGbYe8-fHHfZuEBgw0",
    "self": "Fq_DP3jPGrqfjorOmVg4h5ZJU6W4Ip3gcD82BTb9UGP2zz96",
    "users": [
        {
            "description": "Administrator",
            "external": false,
            "name": "admin",
            "server_group": "group1",
            "server_role": "srv1"
        }
    ]
}

The "self" and "last" cursors are now the same, indicating this is indeed the last page of results, and the "next" cursor is empty (there are no more results after this one).