veza/PAGINATION_STANDARD.md

Pagination Format Standardization

INT-007: Standardize pagination format

Date: 2025-12-25
Status: Completed

Summary

All paginated API responses in Veza now use a consistent, standardized format that matches frontend expectations.

Standard Pagination Format

All paginated responses follow this structure:

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "total_pages": 5,
      "has_next": true,
      "has_prev": false,
      "next_cursor": "optional_cursor_string",
      "prev_cursor": "optional_cursor_string"
    }
  }
}

Pagination Object Fields

• page (number, required): Current page number (1-based)
• limit (number, required): Number of items per page
• total (number, required): Total number of items across all pages
• total_pages (number, required): Total number of pages
• has_next (boolean, required): Whether there is a next page
• has_prev (boolean, required): Whether there is a previous page
• next_cursor (string, optional): Cursor for cursor-based pagination
• prev_cursor (string, optional): Cursor for cursor-based pagination

Implementation

Backend

All paginated responses are now standardized through:

1. PaginationData (internal/handlers/common.go):

   • Standardized struct with snake_case field names
   • Changed HasPrevious → has_prev for consistency
   • Changed PreviousCursor → prev_cursor for consistency

2. BuildPaginationData (internal/handlers/common.go):

   • Helper function to create standardized pagination data
   • Calculates total_pages, has_next, has_prev automatically
   • Used by all handlers for consistent pagination

3. BuildPaginationDataWithCursor (internal/handlers/common.go):

   • Helper for cursor-based pagination
   • Supports both cursor and offset-based pagination

4. Handler Updates:

   • ListTracks: Uses BuildPaginationData
   • ListUsers: Uses BuildPaginationData
   • SearchUsers: Uses BuildPaginationData
   • GetComments: Uses BuildPaginationData
   • SearchLogs: Uses BuildPaginationData

Frontend

The frontend already expects the standardized format:

• PaginationData type matches backend structure
• Components use has_next, has_prev, total_pages
• Pagination component handles all standard fields

Changes Made

Backend Changes

1. internal/handlers/common.go:

   • Updated PaginationData struct to use snake_case consistently
   • Changed HasPrevious → HasPrev
   • Changed PreviousCursor → PrevCursor
   • Added BuildPaginationData helper function
   • Added BuildPaginationDataWithCursor helper function

2. internal/core/track/handler.go:

   • Updated ListTracks to use BuildPaginationData
   • Standardized pagination response format

3. internal/handlers/profile_handler.go:

   • Updated ListUsers to use BuildPaginationData
   • Updated SearchUsers to use BuildPaginationData
   • Standardized pagination response format

4. internal/handlers/comment_handler.go:

   • Updated GetComments to use BuildPaginationData
   • Added has_next and has_prev fields

5. internal/handlers/audit.go:

   • Updated SearchLogs to use BuildPaginationData
   • Standardized pagination format for both page-based and offset-based

Frontend Compatibility

The frontend already supports the standardized format:

• PaginationData type matches backend structure
• All pagination components use standard fields
• No frontend changes required

Migration Notes

• All handlers now use BuildPaginationData helper
• Consistent field naming (snake_case)
• All paginated responses include has_next and has_prev
• Cursor-based pagination supported via optional fields

Files Modified

• veza-backend-api/internal/handlers/common.go
• veza-backend-api/internal/core/track/handler.go
• veza-backend-api/internal/handlers/profile_handler.go
• veza-backend-api/internal/handlers/comment_handler.go
• veza-backend-api/internal/handlers/audit.go
• Created: PAGINATION_STANDARD.md (this document)

Next Steps

1. ✅ Standardize PaginationData struct
2. ✅ Create BuildPaginationData helper
3. ✅ Update all handlers to use standardized format
4. ✅ Verify frontend compatibility
5. ⏳ Add integration tests for pagination format validation