Consuming Paginated REST APIs

Follow a provider's pagination contract while bounding total requests and records. The examples separate the essential operation from the conditions a production implementation must enforce.

What It Does

Follow a provider's pagination contract while bounding total requests and records.

Prerequisites

Use a dedicated development environment with test accounts and records. Separate authorization, validation and error handling from response formatting; never copy demonstration-only secrets into production.

Example 1: Core Behavior

The first example isolates the core operation so its result is easy to understand.

<?php
$pages=[[1,2],[3,4],[5]]; $all=[];
foreach ($pages as $page) { $all=array_merge($all,$page); if (count($all)>100) break; }
echo json_encode($all);

Example 2: Alternative or Failure Case

The second example demonstrates an alternative outcome, rule or failure condition.

<?php
$next='/api/items?cursor=abc';
if (!str_starts_with($next,'/api/items?')) throw new RuntimeException('Unexpected pagination location');
echo $next;

Practical Example: Applying the Rule

This practical workflow performs the relevant operation, with strict error checks. Configure the required transport or database driver before running it.

<?php
$nextPage = 1;
$results = [];
while ($nextPage !== null && $nextPage <= 3) {
    $url = 'https://api.example.test/items?page=' . $nextPage;
    $ch = curl_init($url);
    curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 8, CURLOPT_FOLLOWLOCATION => false]);
    $body = curl_exec($ch);
    if ($body === false || curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) throw new RuntimeException('Page download failed');
    $page = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
    if (!isset($page['items']) || !is_array($page['items'])) throw new UnexpectedValueException('Invalid page schema');
    $results = array_merge($results, $page['items']);
    $nextPage = isset($page['nextPage']) ? filter_var($page['nextPage'], FILTER_VALIDATE_INT) : null;
    if ($nextPage === false) throw new UnexpectedValueException('Invalid cursor');
}
echo 'Downloaded items: ' . count($results);

Important Behavior and Edge Cases

Do not blindly follow untrusted next URLs; constrain allowed hosts and prevent infinite loops.

Comparison with Related Functions or Patterns

Common Beginner Mistakes

Key Takeaways

• Follow a provider's pagination contract while bounding total requests and records.
• Do not blindly follow untrusted next URLs; constrain allowed hosts and prevent infinite loops.
• Offset and cursor pagination require different continuation rules.

Select this API or pattern based on its documented behavior and the trust boundaries in your own application, and test all external integrations against their actual deployments.