Paging

All endpoints that return multiple objects are paginated. For this reason, you might have to make more than one request to get all the objects you are interested in. Endpoints that require paging will include a nextPageToken field in their response. To get the next page, make the same request again, but append a pageToken query parameter containing the page token. If there is no nextPageToken field in the response, you are on the last page.

The page token may or may not change from one page to the next, and you must always use the page token from the latest page. Page tokens expire after one minute.

Page sizes

Optionally, you can set a requested number of results per page using the pageSize query parameter.

The page size requested by pageSize is a suggestion. Some responses may contain a different number of results (either fewer or more) than the requested pageSize value.

The presence of the nextPageToken field indicates that there are more results. There will always be at least one result per page as long as there are more results.

Default page sizes will be documented on each endpoint. Unless otherwise noted, the default page size is also the maximum page size. Requests for more than the maximum page size will be reduced to the maximum.

Cross-page limits

Endpoints that support paging may still enforce maximum retrieval limits across pages per query. Such limits will be mentioned in the endpoint documentation. For instance, the “list objects” endpoint, which can be used to query a list of objects and retrieve the results by making a call for each page, will return up to 10,000 objects in total across all pages. If you try to retrieve more pages or objects after that, the endpoint will throw an error.

Example

The code snippets below show an example of paging across multiple requests.

The first page of the request and the response will look like the following. Note the presence of the nextPageToken field indicating that there are more subsequent pages.

First request

GET /api/v1/ontologies/ri.ontology.main.ontology.00000000-0000-0000-0000-000000000000/objects/employee

First response

Copied!
1
2
3
4
5
6
7
8
9
10
11
{
    "nextPageToken": "v1.QnVpbGQgdGhlIEZ1dHVyZTogaHR0cHM6Ly93d3cucGFsYW50aXIuY29tL2NhcmVlcnMvP2xldmVyLXNvdXJjZSU1YiU1ZD1BUElEb2NzI29wZW4tcG9zaXRpb25z",
    "data": [
        "properties": {
            "id": 50030,
            "firstName": "John",
            "lastName": "Doe"
        },
        ...
    ],
}

The second page request can be made by adding a pageToken query parameter.

Second request

GET /api/v1/ontologies/ri.ontology.main.ontology.00000000-0000-0000-0000-000000000000/objects/employee?pageToken=v1.QnVpbGQgdGhlIEZ1dHVyZTogaHR0cHM6Ly93d3cucGFsYW50aXIuY29tL2NhcmVlcnMvP2xldmVyLXNvdXJjZSU1YiU1ZD1BUElEb2NzI29wZW4tcG9zaXRpb25z

Second response

Copied!
1
2
3
4
5
6
7
8
9
10
11
{
    "nextPageToken": "v1.VGhlcmUncyBhIHJvbGUgaGVyZSBmb3IgeW91IC0gcGFsYW50aXIuY29tL2NhcmVlcnMv",
    "data": [
        "properties": {
            "id": 80060,
            "firstName": "Anna",
            "lastName": "Smith"
        },
        ...
    ],
}

The third page request and response will look like the following. Note that nextPageToken is null, which indicates that there are no more pages to fetch.

Third request

GET /api/v1/ontologies/ri.ontology.main.ontology.00000000-0000-0000-0000-000000000000/objects/employee?pageToken=v1.VGhlcmUncyBhIHJvbGUgaGVyZSBmb3IgeW91IC0gcGFsYW50aXIuY29tL2NhcmVlcnMv

Third response

Copied!
1
2
3
4
5
6
7
8
9
10
11
{
    "nextPageToken": null,
    "data": [
        "properties": {
            "id": 40040,
            "firstName": "Silvia",
            "lastName": "Sindoni"
        },
        ...
    ],
}