Pagination

Endpoints that list data are paginated. Most notably:

GET /records: Lists all DNS names across zones.
GET /records/{zone_name}: Lists DNS names within a specific zone.
GET /records/{zone_name}/{name}/rrsets: Lists Resource Record Sets (RRSets) for a specific DNS name.
GET /zones: Lists all zones.

This means that requests may not return all results, if they exceed the page length.

An Illustrative Example

Suppose a client wants to list all its zones, 10 zones per page.

The starting request

It can start with this request:

GET https://api.noip.com/v1/dns/zones?limit=10&offset=0

The requested page is controlled by the limit and offset query parameters.

limit defines the maximum number of items expected in the page,
and offset defines the starting item in the page.

The first response

And gets a this JSON document as response:

{
    "data": [
        {
            "name": "example1.com",
            // ...
        },
        {
            "name": "example2.com",
            // ...
        },
        // ... up to 10 zones (truncated for brevity)
    ],
    "page": {
        "offset": 0,
        "limit": 10,
        "total": 23
    }
}

The paged response contains a page object that describes the range of the data field. It contains 3 fields:

total: The total number of zones for the user.
limit: The limit of the page. This can be lower than the number requested, because as there is a maximum limit allowed for each endpoint.
offset: An index that identifies the first zone in the response, out of the 23 total.

The second request

Since the 10 out of 23 zones were retrieved, two more requests are needed.

The second request will obtain 10 more zones.

GET https://api.noip.com/v1/dns/zones?limit=10&offset=10

{
    "data": [
        {
            "name": "example11.com",
            // ...
        },
        {
            "name": "example12.com",
            // ...
        },
        // ... up to 10 zones (truncated for brevity)
    ],
    "page": {
        "offset": 10,
        "limit": 10,
        "total": 23
    }
}

The last request

The third and last request will obtain the last 3 remaining zones.

GET https://api.noip.com/v1/dns/zones?limit=10&offset=20

{
    "data": [
        {
            "name": "example21.com",
            // ...
        },
        {
            "name": "example22.com",
            // ...
        },
        {
            "name": "example23.com",
            // ...
        }
    ],
    "page": {
        "offset": 20,
        "limit": 10,
        "total": 23
    },
}

Caveats

There are a few caveats when using paginated endpoints.

The maximum `limit`

The limit in the response may be lower than the limit requested.

Instead of requesting only 10 zones each time, the user could have requested more, and it could've obtained all 23 zones in one request, using a larger limit.

For example, this request sets a limit of 1000 zones per page:

GET https://api.noip.com/v1/dns/zones?limit=1000&offset=0

However, there's a maximum limit for each endpoint. In this case, there is a limit of 50 zones per page:

{
    "data": [
        {
            "name": "example1.com",
            // ...
        },
        {
            "name": "example2.com",
            // ...
        },
        // ... all the 23 zones, truncated for brevity.
    ],
    "page": {
        "offset": 0,
        "limit": 50,
        "total": 23
    }
}

The limit of 50 zones was enough to get all the 23 zones in this situation, but if the user had more than 50 zones, and the limit in the response wasn't checked, the zones in the second page would have been ignored.

Please note that the maximum limit for each endpoint may change in future versions of the API.

Calculating the offset in a sequence of requests

Since the limit can be overridden by the server, and returned in the response, use the response limit to calculate the increment of the offsets.

let offset = 0;
let total = 1; // initial assumption

while (offset < total) {
    const response = await getZones(authorization, url, { limit: 1000, offset });

    offset += response.page.limit;
    total = response.page.total;

    // ... consumption of the response omitted
}

Default values for `limit` and `offset`.

Each endpoint has a default value for limit. The default value for offset is always 0.

Please note that the default limit for each endpoint may change in future versions of the API.

Order stability

The response pages may change depending on the filter, sort and metadata filters. If no filtering or sorting is set, each endpoint has default values for each parameters, resulting in stable pagination.

Please note that the default filtering and sorting for each endpoint may change in future versions of the API.

Concurrent changes

The pages may change if resources are added and removed.