# 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:

```json
{
  "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