Handle pagination

Retrieve paginated results from the BookHub Publisher API using page and limit parameters.

Use pagination to limit the number of results per page for a GET /v2/books request with a large book dataset.

Prerequisites

Before you begin, ensure you meet the following prerequisites:

• Familiarity with BookHub Publisher API v2.
• A valid JWT for authentication.
• Access to your codebase that integrates with the BookHub Publisher API v2.

Step 1: Send a paginated request

To implement pagination with the BookHub Publisher API, construct a request that fetches results in pages using the page and limit parameters.

The following examples use page and limit only. The endpoint also accepts status, sort, and order parameters — see Get all books for details.

def fetch_all_books(base_url, token):
    all_books = []
    page = 1
    while True:
        response = requests.get(
            f"{base_url}/v2/books",
            params={'page': page, 'limit': 20},
            headers={'Authorization': f'Bearer {token}'}
        )
        response.raise_for_status()
        data = response.json().get('data', {})
        if 'pagination' not in data:
            break
        all_books.extend(data.get('books', []))
        if page >= data['pagination']['totalPages']:
            break
        page += 1
    return all_books

The loop exits when page reaches totalPages. If the API returns fewer items than limit, stop after processing that page. If the response does not include a pagination object, exit immediately.

The response includes a pagination object with the total number of items, total pages, and current page.

{
  "status": "success",
  "data": {
    "books": [
      {
        "bookId": "123e4567-e89b-41d4-a716-426614174000",
        "title": "The Great Adventure",
        "author": "Jane Smith",
        "description": "An epic tale of courage and discovery",
        "language": "en-US",
        "publisher": "Adventure Books Inc",
        "publishedDate": "2024-03-15",
        "isbn": "978-0-1234-5678-9",
        "price": 24.99,
        "status": "ACTIVE",
        "coverImages": [
          "https://covers.bookhub.com/great-adventure-front.jpg"
        ],
        "genres": [
          "Fiction",
          "Adventure"
        ],
        "bookFormat": "Hardcover",
        "createdDate": "2024-12-25T10:30:00Z",
        "updatedDate": "2024-12-26T15:45:00Z"
      },
      {
        "bookId": "123e4567-e89b-41d4-a716-426614174001",
        "title": "Mystery at Midnight",
        "author": "Bob Johnson",
        "description": "A gripping mystery set in a small town",
        "language": "en-US",
        "publisher": "Midnight Press",
        "publishedDate": "2024-06-10",
        "isbn": "978-1-23-456789-0",
        "price": 19.99,
        "status": "ACTIVE",
        "coverImages": [
          "https://covers.bookhub.com/mystery-midnight-front.jpg"
        ],
        "genres": [
          "Mystery",
          "Thriller"
        ],
        "bookFormat": "Paperback",
        "createdDate": "2024-12-24T14:20:00Z",
        "updatedDate": "2024-12-24T14:20:00Z"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 5,
      "totalItems": 87,
      "itemsPerPage": 20
    }
  }
}

Error handling

The page parameter defaults to 1. The limit parameter accepts values between 1 and 100 and defaults to 20.

Code	Cause	Resolution
400	Bad request (for example, invalid page or limit parameter)	Provide a valid page or limit parameter and try again.
401	Unauthorized (for example, a missing or invalid JWT)	Provide a valid JWT and try again.
429	Rate limit exceeded (for example, 150 requests per minute)	Wait until the time in the X-RateLimit-Reset header, then retry with the same Idempotency-Key. See Monitor rate limits.

Step 2: Test your implementation

Call the fetch_all_books function with your API base URL and JWT. Verify that it retrieves all books across multiple pages by checking the length of the returned list against totalItems.

BASE_URL = "https://api.bookhub.com/api"
TOKEN = "YOUR_JWT_TOKEN"
books = fetch_all_books(BASE_URL, TOKEN)
print(f"Total books fetched: {len(books)}")

Next steps

Explore related topics:

How-to guides

• Cache book details for faster performance — Use ETag and Cache-Control headers to cache book details and reduce unnecessary API calls.
• Monitor rate limits — Track your API usage to avoid exceeding rate limits.

Reference

• Release notes — Explore all changes in BookHub Publisher API v2, including any updates related to pagination.

---