Region API Pagination

Principal Manager APIs (aka Region APIs) support the pagination of results. That functionality aims to allow clients to fetch all of the entities of the requested type, even if their number is large. The API response will be split into smaller chunks, allowing the client to fetch only as much as is needed. Besides pagination, filtering and sorting facility are also added to the query APIs.
The following query APIs provides a pagination feature:

• Users
• Devices
• Applications
• Tenants
• Groups
• Contracts

Overview

The Principal Manager APIs provide pagination features designed to:

• Reduce the load of the page.
• Retrieve the records beyond 1000 for the given API resource query.
• Query resources page-wise.

The pagination feature supports the following query parameters:

1. Limiting
2. Filtering
3. Sorting

to achieve the below scenarios:

• Fetch the data in specified portions
• Fetch the data in the specified range (i.e., fetching data in the range 300-600)
• Sort results by a specific field
• Get the total number of records to display possible pages
• Filter results by their properties.

Limiting

The limit query parameter is responsible for limiting the records. Users can set a limit for the number of records they want to see in the response.
Following are the requirements to set a limit query parameter:

1. Ensure that the set limit is a positive integer; otherwise, the API responds as follows:

   {
     "errors": [
       {
         "code": "validation_error",
         "title": "Validation failed",
         "detail": "limit must be a positive integer"
       }
     ]
   }
   

2. Ensure that the maximum limit is set to 1000; otherwise, the API responds as follows:

   {
     "errors": [
       {
         "code": "validation_error",
         "title": "Validation failed",
         "detail": "You requested a limit of 2000, but 1000 is the maximum."
       }
     ]
   }
   

Note: If the user does not define any limit, it will be set to 100 records per page by default.

Filtering

The filter query parameter is responsible for filtering the records by their properties, such as Id, SolutionId, Type, and etc. Users can specify the properties for which they want to see the records in the response.

The following table lists all the APIs with their properties that support filter query parameter:

APIs	Properties
Application	Id, SolutionId, Type, Delegation, Name, and Tags
Device	Id, IpId, Identity, Tags, TenantId, SolutionId, ParentId, and ConnectivityProviderId
Group	Id, TenantId, Tags, Name, User, and Device
Tenant	Name and Tags
User	Id, IpId, Identity, Tags, and TenantId

Sorting

The sort query parameter is responsible for sorting the records by their properties (such as Id, SolutionId, Type, etc.) and by the specified order (ascending/descending). Users can specify the sort property and sort order for which they want to see the records in the response.

Sorting format is supported as {sortProperty} {sortOrder}, {sortProperty} {sortOrder}. Sorting is done on multiple columns where columns are separated by "," and sortOrder is provided for a column delimited by space.
An example: /example-api?sort='name asc, id asc'

Following are the requirements to specify a sort query parameter:

1. Ensure that the sortOrder is valid (asc,desc); otherwise, the API responds as follows:

   {
     "errors": [
       {
         "code": "validation_error",
         "title": "Validation failed",
         "detail": "Supported sort order are 'asc','desc'. "
       }
     ]
   }
   

2. If the sortProperty is provided, ensure that APIs properties are supported (see filtering section for APIs supported properties); otherwise, the API responds as follows:

{
  "errors": [
    {
      "code": "validation_error",
      "title": "Validation failed",
      "detail": "{sortProperty} is not supported"
    }
  ]
}

Note: If the user does not define any sortOrder, it will be set as ascending order by default.

Support for Various Operations

The following table lists all the entities of Principal Manager API that support various features described in this document:

APIs	Limiting	Sorting	Filtering
Application	Yes	Yes	Yes
Device	Yes	No	Yes
Tenant	Yes	Yes	Yes
User	Yes	No	Yes
Group	Yes	Yes	Yes

Perform the following steps to define the query parameters in an API: Note: The following procedure is an example for Application API. Users can use the same procedure for other APIs.

1. Specify the sort value in the sort field.
2. Enter the page number in the page field fetch results from the specific page of data.
3. Define the records limit in the limit field.
4. Specify the filter value in the filter field.

Query API Response

{
    "totalCount": 154,
    "data": [
        {
            "solutionId": "d00781aa-f9c0-48ac-8e62-cfd9d8151e06",
            "type": "native",
            "delegation": "user",
            "name": "App 1",
            "redirectUris": [
                "http://localhost:8080"
            ],
            "secret": "***",
            "keyId": "68b09df8-0c23-44a8-b57c-607f6770da07",
            "id": "702ffae2-d3cb-4dcb-a720-f478e9a56ddc",
            "tags": [],
            "grantIds": {
                "instance": [
                    "988d4e66-79fc-4a58-90e0-93be1c9036b5"
                ],
                "region": []
            }
        },
        {
            "solutionId": "d00ed07b-df8e-4bce-bcc3-d9bc3d835a97",
            "type": "background",
            "name": "Device Registration",
            "secret": "1AK0_jE~q95s3~v9Q-1BhlJ~T9ixWW1e1e",
            "keyId": "e4be1d57-4c37-4bf4-b707-45325594e7ee",
            "id": "0e94fc99-8610-4e16-a7cd-3526d5a4fda7",
            "tags": [],
            "grantIds": {
                "instance": [],
                "region": [
                    "3488c378-8e90-4341-bf30-5cb610a1875d"
                ]
            }
        },
        ...
    ]
}