Handling pagination

How to handle API responses with multiple pages

If you make a GET request for /contracts endpoint, instead of getting a huge response with all your contracts' info in a json of million lines, you'll get page information, with the first 24 results in a list under it's results key.

Something like this:

{"page_size": 24,
 "page": 1,
 "last_page": 26,
 "count": 624,
 "next": "https://sandbox.zefort.com/api/contracts/?page=2",
 "previous": null,
 "results": [{"attributes": {"title": "Contract of doom 1",
                             "end_date": null,
                             "effective_date": null,
                             "signed_date": null,
                             "main_language": null},
              "cover_document": {...},
              "id": "ct_1KuKrFqQA25mskTpbK",
              "incomplete": false,
              "num_emails": 0,
              "num_files": 1,
              "num_users": 4,
              ...},
             {"attributes": {"title": "Contract of doom 2",
                             "end_date": null,
                             "effective_date": null,
                             "signed_date": null,
                             "main_language": null},
              "cover_document": {...},
              "id": "ct_1KTeRsjKjCC8H4xSxp",
              "incomplete": false,
              "num_emails": 0,
              "num_files": 1,
              "num_users": 4,
              ...}
             ...
]}

The page structure makes it possible to handle massive amount of search results in a convenient way. The examples below shows how to navigate in it.

  1. Choosing the page manually
  2. Iterating pages

1. Set the page manually

You can choose which page's content is responded to you by adding page parameter with an integer to your request. Likewise you can set the page_size parameter and choose the quantity of results included in one page.

import requests

ZEFORT_APIKEY = 'asfjdkk3k34235k...'
URL = 'https://sandbox.zefort.com/api/contracts/'

response = requests.get(
    URL,
    auth=(ZEFORT_APIKEY, ''),
    params= {
        'page_size': 25,
        'page': 3,
        'status': 'review',
        'receive_time': '20220512-',
        'sort': 'end_date',
        'minimal': True,
    })

ZEFORT_APIKEY="ySLE1mhh6lfRsYa..."

curl -X GET "https://sandbox.zefort.com/api/contracts/?\
page_size=25&\
page=3&\
status=review&\
receive_time=20220512-&\
sort=end_date&\
minimal=True" \
 -u $ZEFORT_APIKEY:

2. Iterating pages

One way of iterating through all the pages, is to create a generator that yields one page at the time and moves on until the final page. The example below is for printing all the titles and ids of certain contracts, because why not:

import requests

ZEFORT_APIKEY = 'asfjdkk3k34235k...'
URL = 'https://sandbox.zefort.com/api/contracts/'
session = requests.Session()

def pages():
    current_page = 1
    total_pages = 2 # Will be updated

    while(current_page <= total_pages):
        page = session.get(
            URL,
            auth=(ZEFORT_APIKEY, ''),
            params={
                'page_size': 100,
                'page': current_page,
                'status': 'done',
                'receive_time': '20220516-',
                'minimal': True,
            })
        total_pages = page.json()['last_page']
        current_page += 1
        yield page

for page in pages():
    # Process the page as you like
    print(*page.json()['results'], sep='\n')