Cursor-based pagination in Rest API

Introduction

Cursor-based pagination helps you get data in small parts without missing or repeating items. It uses a marker (cursor) to remember where you left off.

When you want to show a long list of items in small pages on a website or app.

When data changes often and you want to avoid showing the same item twice or skipping items.

When you want faster and more reliable navigation through large datasets.

When you want to load more items as the user scrolls down (infinite scroll).

Syntax

Rest API

GET /items?limit=10&cursor=abc123

limit sets how many items to get per page.

cursor is a token that points to where to start the next page.

Examples

Get the first 5 products from the list.

Rest API

GET /products?limit=5

Get the next 5 products starting after the product with ID 100.

Rest API

GET /products?limit=5&cursor=eyJpZCI6MTAwfQ==

Sample Program

This is a simple web server using Flask. It returns items in pages. You ask for a page with a limit and an optional cursor. The server finds where to start, sends that many items, and gives a cursor for the next page.

Rest API

from flask import Flask, request, jsonify

app = Flask(__name__)

# Sample data: list of items with IDs
items = [{'id': i, 'name': f'Item {i}'} for i in range(1, 101)]

@app.route('/items')
def get_items():
    limit = int(request.args.get('limit', 10))
    cursor = request.args.get('cursor')

    # Find start index based on cursor
    start_index = 0
    if cursor:
        try:
            start_id = int(cursor)
            # Find the index of the item with id == start_id
            for idx, item in enumerate(items):
                if item['id'] == start_id:
                    start_index = idx + 1
                    break
        except ValueError:
            pass

    # Get the slice of items
    page_items = items[start_index:start_index + limit]

    # Prepare next cursor
    if len(page_items) == limit and (start_index + limit) < len(items):
        next_cursor = str(page_items[-1]['id'])
    else:
        next_cursor = None

    return jsonify({
        'items': page_items,
        'next_cursor': next_cursor
    })

if __name__ == '__main__':
    app.run(debug=True)

Important Notes

Cursor-based pagination is more reliable than page-number pagination when data changes often.

The cursor is usually an encoded value like an ID or timestamp.

Always return the next cursor in the response so the client can request the next page.

Summary

Cursor-based pagination uses a marker to get the next set of data.

It helps avoid missing or repeating items when data changes.

Clients send the cursor to get the next page, and servers return a new cursor if more data exists.