This documentation supports the 20.02 version of BMC CMDB.

To view an earlier version, select the version from the Product version menu.

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.


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
}    
 
 

Here, 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 you the "num_matches" flag is set to true, it returns the number of matching instances. The default value is false.

As a convenience, the full URL of the next page is also provided in the next field (although paginated results do not necessarily need to be traversed in the page order).

The format for the results is a list of objects, where each object represents results for a particular <node kind>. This format supports those endpoint results which might return multiple kinds.

Here is the request for the next one hundred items from the same results set:

curl -i -X GET -H 'Authorization: bearer <your_token>' 
'https://appliance/api/v1.0/data/search?
results_id=SG9zdABuco8EWAIAB9oAAAV84w%3D%3D&query=SEARCH+Host&offset=100'

HTTP/1.1 200 OK
[
    {
        "count": 2446,
        "headings": [...],
        "kind": "Host",
        "next": "https://appliance/api/v1.0/data/search?
results_id=SG9zdABuco8EWAIAB9oAAAV84w%3D%3D&query=SEARCH+Host&offset=200",
        "next_offset": 200,
        "offset": 100,
        "results": [ <next 100 results> ],
        "results_id": "SG9zdABuco8EWAIAB9oAAAV84w=="
    }
]

See the  /data/search  endpoint for full details of navigating paginated results.



Was this page helpful? Yes No Submitting... Thank you

Comments