Pagination

Content

• Overview
• Pagination Parameters
• Pagination Header
• Examples
• API Listing

Overview

ULM includes a variety of APIs that can return multiple results. For instance, GET user/{userId}/features returns all features associated to the given user ID. Since ULM's data model supports many-to-many associations between entities, any one entity can grow to have a significantly large number of associations.

A high number of results within a single response can put a strain on the system or the UI retrieving and rendering those entities. To control the number of results in a given call, a select number of ULM APIs support pagination to break up large results into easily renderable pages.

Pagination Parameters

The optional size and offset request parameters enable the fetching of data in smaller, manageable segments:

A request that exceeds the max size or has a negative offset value results in a HTTP 400 (BAD REQUEST).

Note: Server-side application settings control the size parameter's default and maximum rules:

• system.rest.defaultPageSize controls the size parameter's default value.
• system.rest.maxPageSize controls the size parameter's highest maximum value.

Pagination Header

Successful responses include an X-Total-Count header that indicates the total number of available entities.

Examples

Multiple Page Response

Here is a simple pagination where there is a total count of 4 results broken up into two pages.

GET /membership/1/subscriptions?offset=0&size=2

Header: X-Total-Count = 4
[
  {
    "id": 1,
    "displayName": "Cable TV"
  },
  {
    "id": 2,
    "displayName": "Video on Demand"
  }
]

GET /membership/1/subscriptions?offest=2&size=2

Header: X-Total-Count = 4
[
  {
    "id": 3,
    "displayName": "HBO"
  },
  {
    "id": 4,
    "displayName": "NetFlix"
  }
]

Sending a Request With Zero Size Value

A request size of zero will retrieve all results if the total number of results is less than the max page size.

For example, assume that there are 3 available results, and that system.rest.maxPageSize=5.

GET /membership/1/subscriptions?size=0

Header: X-Total-Count = 3
[
  {
    "id": 101,
    "displayName": "Gaming Streaming Service"
  },
  {
    "id": 2,
    "displayName": "Music Streaming Service"
  },
  {
    "id": 3,
    "displayName": "Movie Streaming Service"
  }
]

A request size of zero returns an error response if the total number of results exceeds max page size.

For example, assume that there are 10 available results, and that system.rest.maxPageSize=5.

"operationError": {
    "code": "max-return-page-size",
    "message": "Total number of results exceeds the maximum page size"
}

Page Size Bigger Than Maximum Allowed

A request with a size value that exceeds the maximum page size returns an error response.

For example, in the call below, assume that system.rest.maxPageSize=10.

GET /membership/1/subscriptions?offset=0&size=20

{
    "operationError": {
        "code": "page-size-error",
        "message": "Requested page size is bigger than allowed maximum size"
    }
}

API Listing

The following table contains GET calls that support pagination parameters, and that return a X-Total-Count header.