Pagination

ZoneVast services paginate list endpoints. The exact format depends on the backend framework, but the concepts are the same: send page and limit parameters, receive metadata about the total results.

Query Parameters

Both frameworks accept the same query parameters:

|| Parameter | Default | Max | Description | ||-----------|---------|-----|-------------| || page | 1 | — | Page number (1-indexed) | || limit | 10–20 | 100 | Items per page |

Note: Some Django services use page_size as an alias for limit. Both are accepted.

Django DRF Pagination

ZoneVast Django services use a shared CustomNumberPagination class from zonevast-lib:

GET /api/v1/project/project/projects/?page=2&limit=20
Authorization: Bearer <token>
X-Project-ID: <project-id>

Response:

{
  "count": 156,
  "total_pages": 8,
  "current_page": 2,
  "next": 3,
  "previous": 1,
  "limit": 20,
  "results": [
    { "id": 21, "title": "Project A" },
    { "id": 22, "title": "Project B" }
  ]
}

Response Fields

|| Field | Type | Description | ||-------|------|-------------| || count | number | Total items across all pages | || total_pages | number | Total number of pages | || current_page | number | Current page number | || next | number or null | Next page number, or null if last page | || previous | number or null | Previous page number, or null if first page | || limit | number | Items per page used for this request | || results | array | The items on this page |

Note: Not all Django views use pagination. Some views (like file attachment lists) return unpaginated arrays. Check the specific endpoint documentation.

NestJS Pagination

NestJS services use a PaginationDto base class with page and limit fields:

GET /api/v1/auctions?page=2&limit=20
Authorization: Bearer <token>
X-Project-ID: <project-id>

Response:

{
  "success": true,
  "message": "Resources retrieved successfully",
  "data": [
    { "id": "uuid-1", "title": "Item A" },
    { "id": "uuid-2", "title": "Item B" }
  ],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 156,
    "totalPages": 8,
    "hasNext": true,
    "hasPrevious": true
  }
}

Response Fields

|| Field | Type | Description | ||-------|------|-------------| || data | array | The items on this page | || pagination.page | number | Current page number | || pagination.limit | number | Items per page | || pagination.total | number | Total items across all pages | || pagination.totalPages | number | Total number of pages | || pagination.hasNext | boolean | Whether a next page exists | || pagination.hasPrevious | boolean | Whether a previous page exists |

Comparison

|| Aspect | Django DRF | NestJS | ||--------|-----------|--------| || Default limit | 10 | 20 | || Max limit | 100 | 100 | || Items key | results | data | || Total key | count | pagination.total | || Page navigation | next / previous (page numbers) | hasNext / hasPrevious (booleans) | || Total pages | total_pages | pagination.totalPages |

Client-Side Implementation

TypeScript Example

interface PaginatedResponse<T> {
  // Django format
  count?: number;
  results?: T[];
  next?: number | null;
  previous?: number | null;
  total_pages?: number;
  current_page?: number;
  limit?: number;

  // NestJS format
  data?: T[];
  pagination?: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNext: boolean;
    hasPrevious: boolean;
  };
}

async function fetchAllPages<T>(
  url: string,
  options: { headers: Record<string, string> }
): Promise<T[]> {
  const allItems: T[] = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const res = await fetch(`${url}?page=${page}&limit=100`, { headers: options.headers });
    const data: PaginatedResponse<T> = await res.json();

    // Handle both formats
    const items = data.results ?? data.data ?? [];
    allItems.push(...items);

    // Check if more pages exist
    if (data.pagination) {
      hasMore = data.pagination.hasNext;
    } else {
      hasMore = data.next !== null;
    }
    page++;
  }

  return allItems;
}

What's Next

• Search & Filtering — How to filter and search lists
• API Response Format — General response structure
• Error Responses — Error format specification