94be6edceb3790bbdf8dabe8f2de9be2fc82f323
2
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 john-okeefe
|
54d3ae785a |
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.
|
||
|
john-okeefe
|
2022595fd4 |
test(api): add Bruno API collection for saved filters
Add comprehensive Bruno OpenCollection YAML files for testing
the saved filters API with 9 request files and scenarios.
Main CRUD Requests (4 files):
1. List Saved Filters.yml
- GET /api/saved-filters?resource_type=media-items
- Documents resource_type parameter requirement
- Example responses with JSONB filters
2. Create Saved Filter.yml
- POST /api/saved-filters
- Complete request body documentation
- All filter field examples (genre, author, sort, year, etc.)
- Validation rules (max 100 chars, uniqueness)
3. Update Saved Filter.yml
- PUT /api/saved-filters/{filter_id}
- Immutability notes (resource_type can't change)
- Duplicate name validation
- Updated timestamp behavior
4. Delete Saved Filter.yml
- DELETE /api/saved-filters/{filter_id}
- 204 No Content response
- Security considerations
Scenario Test Files (5 files):
1. Duplicate Name Validation.yml
- Tests 409 Conflict on duplicate names
- Per-user + per-resource-type uniqueness
- Example bash test script
2. User Isolation - Cross-User Access.yml
- Tests users can't access each other's filters
- Security: 404 instead of 403 (prevents enumeration)
- Complete multi-user test scenario
- Database-level isolation documentation
3. Multiple Resource Types.yml
- Tests generic design with different resource types
- Same name allowed for different types (media-items, collections, devices)
- Examples for each resource type
- Extensibility benefits explained
4. Complete CRUD Workflow.yml
- End-to-end lifecycle test (6.5K file)
- Shell script with all steps: Create → Read → Update → Delete → Verify
- Success criteria checklist
- Copy-paste ready test script
5. Filter Validation - Edge Cases.yml
- 12 different validation test cases
- Empty names, missing fields, invalid UUIDs
- Unicode support (emoji, CJK characters)
- Malformed JSON handling
- Special characters and XSS attempts
Documentation Features:
- {{base_url}} variable substitution
- auth: inherit for authentication
- Comprehensive docs: sections with examples
- Shell commands ready to copy-paste
- Expected status codes and responses
- Error handling examples
- Security best practices
Total: 9 YAML files covering all CRUD operations and edge cases
Usage:
- Import into Bruno/Postman for API testing
- Use for manual testing during development
- Reference for API contract validation
- Example curl commands for documentation
Part of: Saved Filters Implementation (Phase 5: Testing & Documentation)
Related: #saved-filters-feature
|