How to use APIs: Pagination | OverIT Knowledge Hub

Introduction

Pagination only applies to services which return a collection resource, it is needed to enable clients to get a subset of the entire resource, thus avoiding performance and memory issues, while also allowing consumers to decide how many resources of the collection they want to receive.

To enable pagination in one of OverIT APIs, the _page parameter can be used which can be used to specify the desired page and desired number of resources, via unexploded query parameter.

Request QueryParameters

The _page object publishes two parameters for the client to fill: num and size.

Num

This parameter is an Integer that allows the client to specify which page number it wants to retrieve. This parameter is mandatory, which means that once the _page object is specified, at least the num parameter has to be specified. The default value is zero, which means that the first page will be retrieved in case the _page object is not specified by the client.

Size

This parameter is an Integer that allows the client to specify the maximum number of entries that a single page is allowed to contain. The default value is zero, which means that a page is allowed to contain any number of entries, effectively disabling the pagination mechanism up until the default maximum size which is 10.000 (ten thousands).

The Page object does not allow for endless resource instances in the response, it has a default maximum of 10.000 (ten thousands) instances per call. This default can be customized by a system configurator, changing the value of the company configuration parameters.

There are three standard sizes for pages:

Small: 100 instances
- company.core.rs.pageSize.s
Medium: 1.000 instances
- company.core.rs.pageSize.m
Large: 10.000 instances
- company.core.rs.pageSize.l

This sizing configuration will be available per company, so that every company may have a different sizing on each API.

Please note that for any request sent with a page size > 10000 (ten thousands), the server will ignore the requested size and the response resource instances will be capped at the limit.

Requests with negative page size (size < 0) will receive an error response with HTTP status code 400 (Bad Request).

Parameter	Optional	Description
_page	Yes	QueryParameter used to request server-side pagination. The default pagination if the parameter is not specified is implemented based on the specific resource needs, typically the first page is return with either all results or a fixed subset.
num	No	Number of the page to be returned.
size	Yes	Maximum number of entries returned per page (0 <= size <= 10000).

Response payload

The _page object contains two fields: num and hasMore.

num

This field is an Integer which represents the number of the page that is being returned by the API.

hasMore

This response parameter is a boolean which indicates whether there are more pages that can be requested by the client.

Parameter	Description
_page	Object which contains the `num` and `hasMore` fields.
num	Number of the page which is being returned.
hasMore	Its value is either `true` or `false` based on whether more pages can be requested.

Example

Request

Bash

curl "<https://api.overit.cloud/api/r1/work-order?_page=num,0,size,10>" \
  -H "Authorization: Bearer <personal_access_token>"

Response

JSON

"content": [
  {
    "id": 0,
    "code": "string",
    "description": [
      {
        "lang": "string",
        "value": "string"
      }
    ],
    "order": 0,
    "active": true,
    "urgency": true,
    "color": "string"
  }
],
"_page": {
  "num": 0,
  "hasMore": true
}