john-okeefe
54d3ae785a
Add comprehensive documentation for GET /api/saved-filters/:id endpoint
including Bruno API collection, developer API docs, user documentation,
and implementation plan with frontend integration phase.
Bruno API Collection (bruno/saved-filters/Get Saved Filter By ID.yml):
- New Bruno request file for GET /:id endpoint
- Includes comprehensive documentation with examples
- Documents all status codes (200, 400, 401, 404)
- Provides example curl commands and use cases
- Uses variable placeholders ({{base_url}}, {{filter_id}})
- Follows existing Bruno YAML patterns
API Documentation (docs/developer/api/saved-filters/index.md):
- Added GET /api/saved-filters/:id endpoint documentation
- Example request with UUID parameter
- Example response showing filter object structure
- Error responses documented (400, 401, 404)
- Use cases: Mobile apps, SPAs, editing, verification
User Documentation (docs/user/library-browsing.md):
- Updated "Loading Saved Filters" section
- Removed "feature coming soon" language
- Added step-by-step instructions for loading filters
- Added tips section with visual indicators
- Added "Managing Saved Filters" section
- Added "Common Use Cases" (genre, author, series)
- Emphasizes instant feedback (no page reload)
Implementation Plan (GET_SAVED_FILTER_BY_ID_IMPLEMENTATION.md):
- Added Phase 7: User Documentation Update
- Added Phase 8: Frontend Integration (bookshelf.ts)
- Shows loadFilter() implementation
- Hybrid Alpine.js + HTMX approach
- Maintains SSR-first principles
- API call on user interaction, not page load
- Populates hidden form fields
- Triggers HTMX to apply filter
- Updated Summary of Changes: 7 files, ~344 lines
- Updated Checklist with frontend and user docs tasks
- Added frontend testing tasks
SSR-First Compliance:
- Initial page load: Server renders everything (no API calls)
- User interaction only: API called when user clicks filter
- No async x-init data fetching
- Progressive enhancement maintained
Documentation Structure:
- Developer docs: API reference for integration
- User docs: Step-by-step usage instructions
- Bruno: API contract testing
- Implementation plan: Complete development guide
All documentation follows established patterns and includes examples.
65 lines
1.7 KiB
YAML
65 lines
1.7 KiB
YAML
info:
|
|
name: Get Saved Filter By ID
|
|
type: http
|
|
seq: 4
|
|
http:
|
|
method: GET
|
|
url: "{{base_url}}/api/saved-filters/{{filter_id}}"
|
|
auth: inherit
|
|
|
|
docs: |-
|
|
## Get Saved Filter By ID
|
|
|
|
Retrieves a single saved filter by its ID.
|
|
|
|
**Method:** GET
|
|
|
|
**Endpoint:** /api/saved-filters/:id
|
|
|
|
**Authentication:** Required (Bearer token)
|
|
|
|
**URL Parameters:**
|
|
- `id` (UUID, required): The unique identifier of the saved filter
|
|
- Example: "550e8400-e29b-41d4-a716-446655440000"
|
|
- Must be a valid UUID format
|
|
|
|
**Response:**
|
|
Single saved filter object:
|
|
```json
|
|
{
|
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"name": "My Sci-Fi Books",
|
|
"resource_type": "media-items",
|
|
"filters": {
|
|
"genre_filter": "Science Fiction",
|
|
"sort": "title ASC"
|
|
},
|
|
"created_at": "2024-03-20T12:00:00Z",
|
|
"updated_at": "2024-03-20T12:00:00Z"
|
|
}
|
|
```
|
|
|
|
**Status Codes:**
|
|
- 200: Success - Returns the saved filter
|
|
- 400: Bad Request - Invalid filter ID format
|
|
- 401: Unauthorized - Invalid or missing authentication token
|
|
- 404: Not Found - Filter doesn't exist or doesn't belong to user
|
|
|
|
**Example Usage:**
|
|
```bash
|
|
# Get a specific saved filter
|
|
curl -H "Authorization: Bearer YOUR_TOKEN" \
|
|
"{{base_url}}/api/saved-filters/550e8400-e29b-41d4-a716-446655440000"
|
|
```
|
|
|
|
**Notes:**
|
|
- Filters are user-specific (ownership verified via JWT)
|
|
- Returns 404 if filter doesn't exist OR doesn't belong to authenticated user
|
|
- Use `GET /api/saved-filters?resource_type=X` to list all filters first
|
|
|
|
**Scenarios:**
|
|
- Get filter by ID from list response
|
|
- Load filter details for editing
|
|
- Verify filter exists before updating
|
|
- Mobile app on-demand filter loading
|