Pagination¶

Overview¶

Pagination is a technique for dividing large datasets into smaller, manageable chunks or “pages.” This approach is essential when working with APIs that return extensive datasets, as it improves performance, reduces server load, and enhances user experience.

Key Benefits¶

Performance: Faster response times and reduced memory usage
Scalability: Handles large datasets without overwhelming servers
User Experience: Better navigation through large result sets
Network Efficiency: Reduces bandwidth usage and transfer times

How Pagination Works in Nakisa APIs¶

The Nakisa API uses offset-based pagination with the following parameters:

Core Parameters¶

Parameter	Type	Default	Description
`page`	integer	0	Page number (0-based indexing)
`size`	integer	100	Number of records per page

Request Format¶

GET /api/v1/{endpoint}?page={page}&size={size}

Example:

GET /api/v1/contracts?page=2&size=50

Response Structure¶

Paginated responses include metadata to help navigate through the dataset:

{
    "content": [
        ...
    ],
    "page": {
        "size": 3,
        "totalElements": 468,
        "totalPages": 156,
        "number": 0
    }
}

Response Fields Explained¶

Field	Description
`content`	Array of records for the current page
`page.size`	Number of records per page
`page.totalElements`	Total number of records in the dataset
`page.totalPages`	Total number of pages available
`page.number`	Current page number (0-based)

Implementation Examples¶

cURL Examples¶

Basic Pagination Request:

curl -X GET 'https://{base-url}/api/v1/contracts?page=0&size=50' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json'

Iterating Through All Pages:

#!/bin/bash
BASE_URL="https://{base-url}"
API_KEY="YOUR_API_KEY"
ENDPOINT="contracts"
PAGE_SIZE=50

# Get first page to determine total pages
response=$(curl -s -X GET "$BASE_URL/api/v1/$ENDPOINT?page=0&size=$PAGE_SIZE" \
  -H "x-api-key: $API_KEY" \
  -H 'Content-Type: application/json')

total_pages=$(echo $response | jq -r '.totalPages')

echo "Total pages: $total_pages"

# Iterate through all pages
for ((page=0; page<total_pages; page++)); do
  echo "Fetching page $page of $total_pages"
  curl -X GET "$BASE_URL/api/v1/$ENDPOINT?page=$page&size=$PAGE_SIZE" \
    -H "x-api-key: $API_KEY" \
    -H 'Content-Type: application/json' \
    -o "page_${page}.json"
done

Error Handling and Troubleshooting¶

Common Error Scenarios¶

Error Code	Cause	Solution
400 Bad Request	Invalid page number (negative)	Use `page=0` for first page
400 Bad Request	Page size too large	Reduce size to 20-100
429 Too Many Requests	Rate limit exceeded	Implement exponential backoff
500 Internal Server Error	Server processing error	Retry with exponential backoff
404 Not Found	Endpoint doesn’t support pagination	Check API documentation

Best Practices¶

Performance Optimization¶

Optimal Page Size: Use 20-100 records per page for best performance
Consistent Page Sizes: Keep page size consistent across requests
Caching: Cache pagination metadata to avoid unnecessary requests
Concurrent Requests: Use parallel requests carefully with proper rate limiting

User Experience¶

Progress Indicators: Show loading progress for multi-page operations
Error Recovery: Provide clear error messages and retry options
Empty States: Handle empty result sets gracefully
Navigation: Implement intuitive page navigation controls

Data Integrity¶

State Management: Store pagination state for interrupted operations
Consistency: Handle concurrent data changes appropriately
Validation: Validate page numbers and sizes before requests
Monitoring: Track pagination performance and errors

Monitoring and Debugging¶

Key Metrics to Track¶

Response Times: Monitor page fetch performance
Error Rates: Track pagination-related errors
Rate Limit Hits: Monitor API usage patterns
Page Size Efficiency: Optimize based on usage patterns

Debugging Tips¶

Log Request Details: Include page parameters in logs
Validate Responses: Check response structure consistency
Monitor Memory Usage: Watch for memory leaks in large datasets
Test Edge Cases: Verify behavior with empty datasets

Conclusion¶

Effective pagination is crucial for building scalable applications with the Nakisa API. By following these patterns and best practices, you can ensure optimal performance, reliable data retrieval, and excellent user experience.