docs: add GET /:id endpoint documentation and update implementation plan

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.
This commit is contained in:
2026-03-21 22:37:30 -04:00
parent 0960e36f30
commit 54d3ae785a
4 changed files with 347 additions and 5 deletions
+43
View File
@@ -104,3 +104,46 @@ Delete a saved filter.
**Error Responses:**
- 404 Not Found - Filter doesn't exist or doesn't belong to user
### GET /api/saved-filters/:id
Retrieve a single saved filter by ID.
**URL Parameters:**
- `id` (UUID, required) - Filter ID to retrieve
**Response:** Single saved filter object (HTTP 200)
**Example Request:**
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \\
"http://localhost:8765/api/saved-filters/550e8400-e29b-41d4-a716-446655440000"
```
**Example Response:**
```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"
}
```
**Error Responses:**
- 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
**Use Cases:**
- Mobile apps: Fetch filter details on-demand
- SPAs: Load filter data without page reload
- Editing: Pre-fill filter update form
- Verification: Check filter exists before operations
---
+43 -2
View File
@@ -12,8 +12,49 @@ The bookshelf page allows you to save custom filter presets for quick access.
### Loading Saved Filters
After saving filters, you can quickly load them from the saved filters dropdown (feature coming soon). For now, saved filters persist across page refreshes.
After saving filters, you can quickly load them from the saved filters dropdown:
### Filter Privacy
1. Click the **📋 Saved Filters** button (next to the Save Filter button)
2. Select a filter from the dropdown list
3. The filter values are automatically applied to the form
4. Your books are instantly filtered to show matching results
**Tips:**
- Saved filters appear in the dropdown with their names
- Hover over a filter to see a delete button (🗑️)
- Click a filter name to apply it instantly
- Filters are applied without page reload (instant feedback)
### Managing Saved Filters
**View Saved Filters:**
- Saved filters are displayed in the dropdown
- Each filter shows its name (e.g., "My Sci-Fi Books")
**Delete a Filter:**
1. Click the **📋 Saved Filters** button
2. Hover over the filter you want to delete
3. Click the **🗑️** delete button
4. Confirm deletion
5. The filter is removed from your list
**Filter Privacy:**
Saved filters are **private to your account**. Other users cannot see or modify your filters.
### Common Use Cases
**Reading by Genre:**
1. Filter by genre: "Science Fiction"
2. Save as "Sci-Fi Books"
3. Quickly access all your sci-fi collection anytime
**Author Collections:**
1. Filter by author: "Isaac Asimov"
2. Save as "Asimov Books"
3. Switch between different author collections instantly
**Series Tracking:**
1. Filter by series: "Foundation"
2. Save as "Foundation Series"
3. Track your progress through a series