agatha
781be909bc
Page size changes from 50 to 24. Library now shows discrete page navigation with a "Page N of M" indicator, total image count, and URL state (?page=N) so pages are bookmarkable and the browser Back button works. Tag filter resets to page 1. Out-of-range page params are clamped silently. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
53 lines
1.7 KiB
Markdown
53 lines
1.7 KiB
Markdown
# Contract: Image List Pagination Query
|
|
|
|
No new API endpoints are introduced. This document records the existing API contract the UI relies on for pagination.
|
|
|
|
## Endpoint
|
|
|
|
```
|
|
GET /api/v1/images?limit={limit}&offset={offset}&tags={tags}
|
|
```
|
|
|
|
## Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|---------|----------|--------------------------------------------------|
|
|
| `limit` | integer | No | Images per page. UI sends `24`. Max is 100. |
|
|
| `offset` | integer | No | Number of images to skip. UI computes `(page-1) * 24`. |
|
|
| `tags` | string | No | Comma-separated tag names for AND-filter. |
|
|
|
|
## Response
|
|
|
|
```json
|
|
{
|
|
"items": [ /* ImageRecord[] */ ],
|
|
"total": 143,
|
|
"limit": 24,
|
|
"offset": 48
|
|
}
|
|
```
|
|
|
|
| Field | Type | Description |
|
|
|----------|---------|--------------------------------------------------|
|
|
| `total` | integer | Total images matching the filter (all pages). |
|
|
| `limit` | integer | Page size echoed back. |
|
|
| `offset` | integer | Offset echoed back. |
|
|
| `items` | array | Images for this page only. |
|
|
|
|
## UI-Computed Values
|
|
|
|
```
|
|
totalPages = Math.ceil(total / limit) // e.g. ceil(143 / 24) = 6
|
|
currentPage = offset / limit + 1 // e.g. 48 / 24 + 1 = 3
|
|
offset = (page - 1) * limit // e.g. (3 - 1) * 24 = 48
|
|
```
|
|
|
|
## URL State
|
|
|
|
| Query Param | Source | Example |
|
|
|-------------|---------------------|------------------|
|
|
| `page` | current page number | `?page=3` |
|
|
| `tags` | active tag filters | `?tags=cat,funny` |
|
|
|
|
Both params coexist: `/?page=3&tags=cat,funny`
|