Pagination

List types#

List and search operations return one of two types. Each is an Iterable<T> over the pages loaded so far and does not implement java.util.List.

The two types have the same methods.

import com.eqixiac.equinix.core.http.response.PaginatedFilteredList;
import com.eqixiac.equinix.core.http.response.Pagination;
import com.eqixiac.equinix.fabric.model.Connection;

PaginatedFilteredList<Connection> connections = fabric.connections().search();

for (Connection c : connections) {                 // the pages loaded so far: initially page one
    System.out.println(c.getName() + " " + c.getState());
}

while (connections.hasNextPage()) {                // lazy: one request per call
    connections.next();
}

List<Connection> all = fabric.connections().search().loadAll().toList();   // eager: every page, then a snapshot

Pagination page = connections.getPagination();
Long total = page.getTotal();                      // null on endpoints that omit it
boolean last = page.isLastPage();                  // also true when the endpoint omits totals

stream() streams the loaded items. get(int) and size() also refer to the loaded items, so call loadAll() first when the whole set matters.

Paging rules#

The paging code follows four rules, and a WireMock regression test asserts each of them on the request URL or body.

1. The SDK computes the next offset from the pagination block in the server's response. Fabric caps limit at 100, so a request for limit=500 returns 100 rows, and the next request asks for offset=100 where a calculation from the requested limit would ask for offset=500 and skip 400 rows.
2. The SDK sends a caller-supplied offset unchanged. Earlier releases rounded it down to a multiple of the limit.
3. Paging stops when the server returns an empty page or repeats the offset of the previous page, even if total reports more rows, and the repeated page is discarded. Before 4.0, loadAll() could loop without end against such a response.
4. The paging state advances only after a page was fetched successfully. A failed fetch leaves the list on the previous page, and a retry requests the same page.

Envelope variants#

The services wrap list responses in three different envelopes, and the SDK reads each of them.

Token pagination in IAM and STS#

IAM and STS list endpoints page with an opaque token. Their methods return a page object that carries the items and getNextPageToken(). Pass the token back to fetch the next page.

import com.eqixiac.equinix.iam.model.json.RoleList;

RoleList roles = iam.roles().list();
while (roles.getNextPageToken() != null) {
    roles = iam.roles().list(roles.getNextPageToken(), 50, null);
}

Filters and sorts#

Fabric searches take a FilterPropertyList and a SortPropertyList. The property names are the JSON pointers the Fabric specification lists for each search.

import com.eqixiac.equinix.fabric.model.implementation.filter.FilterPropertyList;
import com.eqixiac.equinix.fabric.model.implementation.filter.FilterType;
import com.eqixiac.equinix.fabric.model.implementation.sort.SortPropertyList;

FilterPropertyList filter = new FilterPropertyList(FilterType.AND)
    .equals("/project/projectId", projectId)
    .in("/operation/equinixStatus", List.of("PROVISIONED", "PROVISIONING"));

PaginatedFilteredList<Connection> active =
    fabric.connections().search(filter, new SortPropertyList().desc("/changeLog/updatedDateTime"));

Some Fabric searches reject a request without a specific filter. The live service on 2026-11-11 required a subject, project or organization filter for cloud-event and metric searches, connection type, bandwidth and both access-point types for price searches, and a non-empty filter.and for the Digital LOA search. MetricQuery and CloudEventQuery build the mandatory filters, see Observability.