Pagination scripts

Introduction

If a standard pagination type can't meet your pagination requirements, you can create a custom script and apply this as the pagination method for endpoints.

Elements of a pagination script

Pagination scripts typically include:

• Inputs

• Outputs

Inputs

Expected inputs must be inside the payload key of the data array. These are summarised below:

• Request

• Response

• Payload

Request

An array/object representing the request parts for the current page:

Field	Summary	Example
body	A string version of the body.	$returnPayload['body'] = $payload['request']['body'];
headers	An array/object containing a key/value map of request headers.	$returnPayload['headers'] = $payload['request']['headers'];
method	The HTTP method.	$returnPayload = [ 'has_next_page' => false, 'method' => 'GET' ];
url	The entire URL used in the request.	$returnPayload['url'] = $nextPage;

Response

An array/object containing the response parts returned from the request:

Field	Summary	Example
headers	An array/object containing a key/value map or response headers.	$links = $payload['response']['headers']['link'][0];
status_code	The HTTP response code.

Payload

The content saved as the payload. For example:

$payload = json_decode($data['payload'], true);

Outputs

If has_next_page is true, a JSON-encoded array/object should be returned (within the payload field) with the following:

Field	Summary	Example
has_next_page	Whether or not there is another page to be fetched.	$returnPayload['has_next_page'] = true;
url	The URL to use for the next page request.	$returnPayload['url'] = $nextPage;
headers	The headers to use for the next page request.	$returnPayload['headers'] = $payload['request']['headers'];
method	The HTTP method to use for the next page request.	$returnPayload['method'] = $payload['request']['method'];
body	The body content to use in the next request.	$returnPayload['body'] = $payload['request']['body'];

Pagination script example

The sample script below demonstrates link header functionality.

Link header pagination script

 <?php

/**
 * Handler function.
 *
 * @param array $data [
 *      'payload'   => (string|null) the payload as a string|null
 *      'variables' => (array[string]string) any variables as key/value
 *      'meta'      => (array[string]string) any meta as key/value
 *      'flow'      => (array[mixed]) current flow data, including variables
 *    ]
 *
 * @return array $data Structure as above, plus 'logs' => (array[string]) Logs to be written to flow run log after script execution
 */


/**
 * Get next page url from link header string
 */
function getNext(string $linkHeaderString): string|null {
    if (!str_contains($linkHeaderString, 'rel="next"')) {
        return null;
    }

    $stringParts = explode(',', $linkHeaderString);

    $nextLinkString = count($stringParts) === 1 ? $stringParts[0] : $stringParts[1]; 

    $matches = [];

    preg_match_all('/<(.+)>;\s?rel="([A-z]*)"/', $nextLinkString, $matches);

    return $matches[1][0];
}

function handle($data)
{
    $payload = json_decode($data['payload'], true);

    $returnPayload = [
        'has_next_page' => false,
        'method' => 'GET'
    ];

    if (array_key_exists('response', $payload)) {
        if (array_key_exists('headers', $payload['response'])) {
            if (array_key_exists('link', $payload['response']['headers'])) {
                /** check if the header contains the next page link
                    Header will be in the format:

                    <https://custom-peaks-1.myshopify.com/admin/api/2023-04/customers.json?limit=50&page_info=eyJkaXJlY3Rpb24iOiJwcmV2IiwibGFzdF9pZCI6NzIyMjM0MzA0MTE4MiwibGFzdF92YWx1ZSI6MTcwMzE2NDgxMDAwMH0>; rel="previous", <https://custom-peaks-1.myshopify.com/admin/api/2023-04/customers.json?limit=50&page_info=eyJkaXJlY3Rpb24iOiJuZXh0IiwibGFzdF9pZCI6Njg2MjY2MjUzMzI3OCwibGFzdF92YWx1ZSI6MTY4NjM1MDU1OTAwMH0>; rel="next"
                */
                $links = $payload['response']['headers']['link'][0];

                $nextPage = getNext($links);

                if ($nextPage) {
                    $returnPayload['has_next_page'] = true;
                    $returnPayload['url'] = $nextPage;
                    $returnPayload['body'] = $payload['request']['body'];
                    $returnPayload['headers'] = $payload['request']['headers'];
                }
            }
        }
    }


    return [
        'payload' => json_encode($returnPayload)
    ];
}