Pagination schemes for REST API responses

Several endpoints have the potential to return large amounts of data in their responses. These endpoints follow a standard approach for returning paginated results. For example, a search for all Hosts in the system could find more than the default page limit of 100 results. In this case, the endpoint returns the first 100 results, and additional fields that provide links to the next page.

In the following example of the response, the value of the "offset" field is the starting index of the first item in this page of results. The Default value is 0. The "limit" field defines the number of Instances to be retrieved. The default value is 500. When the "num_matches" flag is set to true, it returns the total number of matching instances. The default value is false.

curl -i -X GET -H 'Authorization: bearer <your_token>'
'https://<host name>:<port number>
/api/cmdb/v1.0/instances/BMC.ASSET/BMC.CORE/BMC_ComputerSystem?
offset=0&limit=5&dataset_mask=0&attributes=Name,ShortDescription&num_matches=true'

URL: https://<host name>:<port number>
/api/cmdb/v1.0/instances/BMC.ASSET/BMC.CORE/BMC_ComputerSystem?
offset=0&limit=5&dataset_mask=0&attributes=Name,ShortDescription&num_matches=true

HTTP/1.1 200 OK
{
   "instances": [
       {
           "instance_id": "OIGAA5V0HHF21AOP5NOBOP5NOBM5Y9",
           "class_name_key": {
               "name": "BMC_ComputerSystem",
               "namespace": "BMC.CORE"
           },
           "attributes": {
               "Name": "instances_CS1",
               "ShortDescription": "n/a"
           },
           "_links": {
               "self": [
                   {
                       "href": "https://<host name>:<port number>
/api/cmdb/v1.0/instances/BMC.ASSET/BMC.CORE/BMC_ComputerSystem/OIGAA5V0HHF21AOP5NOBOP5NOBM5Y9"
                   }
               ]
           }
       },
       {
           "instance_id": "OIGAA5V0HHF21AOP5NOBOP5NOBM5YK",
           "class_name_key": {
               "name": "BMC_ComputerSystem",
               "namespace": "BMC.CORE"
           },
           "attributes": {
               "Name": "instances_CS2",
               "ShortDescription": "n/a"
           },
           "_links": {
               "self": [
                   {
                       "href": "https://<host name>:<port number>
/api/cmdb/v1.0/instances/BMC.ASSET/BMC.CORE/BMC_ComputerSystem/OIGAA5V0HHF21AOP5NOBOP5NOBM5YK"
                   }
               ]
           }
       },
       {
           "instance_id": "OIGAA5V0HHF21AOPOD1DOPOD1DDL6K",
           "class_name_key": {
               "name": "BMC_ComputerSystem",
               "namespace": "BMC.CORE"
           },
           "attributes": {
               "Name": "instances_CS1",
               "ShortDescription": "n/a"
           },
           "_links": {
               "self": [
                   {
                       "href": "https://<host name>:<port number>
/api/cmdb/v1.0/instances/BMC.ASSET/BMC.CORE/BMC_ComputerSystem/OIGAA5V0HHF21AOPOD1DOPOD1DDL6K"
                   }
               ]
           }
       },
       {
           "instance_id": "OIGAA5V0HHF21AOPOD1DOPOD1DDL6L",
           "class_name_key": {
               "name": "BMC_ComputerSystem",
               "namespace": "BMC.CORE"
           },
           "attributes": {
               "Name": "instances_CS2",
               "ShortDescription": "n/a"
           },
           "_links": {
               "self": [
                   {
                       "href": "https://<host name>:<port number>
/api/cmdb/v1.0/instances/BMC.ASSET/BMC.CORE/BMC_ComputerSystem/OIGAA5V0HHF21AOPOD1DOPOD1DDL6L"
                   }
               ]
           }
       },
       {
           "instance_id": "OIGAA5V0HHF21AOPOD1DOPOD1DDL6M",
           "class_name_key": {
               "name": "BMC_ComputerSystem",
               "namespace": "BMC.CORE"
           },
           "attributes": {
               "Name": "instances_CS3",
               "ShortDescription": "n/a"
           },
           "_links": {
               "self": [
                   {
                       "href": "https://<host name>:<port number>
/api/cmdb/v1.0/instances/BMC.ASSET/BMC.CORE/BMC_ComputerSystem/OIGAA5V0HHF21AOPOD1DOPOD1DDL6M"
                   }
               ]
           }
       }
   ],
   "num_matches": 292
}

Pagination schemes for REST API responses

On this page