138 lines
4.3 KiB
Markdown
138 lines
4.3 KiB
Markdown
# 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
|
|
|