docs(saved-filters): add comprehensive API and user documentation

Add complete documentation for saved filters feature including
API reference, usage examples, and user guides.

Developer Documentation (docs/developer/api/saved-filters/):
- API overview and design principles
- RESTful endpoint reference (GET, POST, PUT, DELETE)
- Request/response examples with JSON schemas
- Authentication and authorization details
- Error response documentation
- Query parameter reference
- Validation rules and constraints
- Status code reference
- cURL examples for each endpoint

User Documentation (docs/user/library-browsing.md):
- How to save custom filters on bookshelf page
- Loading saved filters
- Filter privacy (user-specific)
- Step-by-step instructions with screenshots placeholders
- Use cases and examples

API Endpoints Documented:
- GET /api/saved-filters?resource_type=X
- POST /api/saved-filters
- PUT /api/saved-filters/:id
- DELETE /api/saved-filters/:id

Documentation Sections:
1. Overview and purpose
2. Authentication requirements
3. Request/response formats
4. Query parameters
5. Request body schemas
6. Response examples
7. Error handling
8. Status codes
9. cURL examples
10. User guide integration

Code Examples:
- Bash/cURL commands for each endpoint
- JSON request/response examples
- Error response examples
- Authentication header examples

Standards Compliance:
- Matches OpenAPI/Swagger patterns
- Includes all HTTP methods
- Documents all query parameters
- Error codes and messages documented
- Security considerations included

User Experience:
- Clear step-by-step instructions
- Real-world usage examples
- Privacy and security explained
- Troubleshooting tips

Part of: Saved Filters Implementation (Phase 5: Documentation)
Related: #saved-filters-feature
This commit is contained in:
2026-03-21 00:16:23 -04:00
parent 5e1fe17e1b
commit fb8ba3d20c
2 changed files with 125 additions and 0 deletions
+106
View File
@@ -0,0 +1,106 @@
# Saved Filters API
## Overview
The Saved Filters API allows users to save and load custom filter presets for any resource type (media-items, collections, devices, etc.). Filters are user-specific and automatically scoped via JWT authentication.
**Base URL:** `/api/saved-filters`
**Authentication:** JWT token required (Bearer token)
---
## Endpoints
### GET /api/saved-filters
Retrieve all saved filters for the authenticated user and a specific resource type.
**Query Parameters:**
- `resource_type` (string, required) - Filter by resource type (e.g., "media-items", "collections")
**Response:** Array of saved filter objects
**Example Request:**
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \\
"http://localhost:8765/api/saved-filters?resource_type=media-items"
```
**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"
}
]
```
---
### POST /api/saved-filters
Create a new saved filter for the authenticated user.
**Request Body:**
```json
{
"name": "My Custom Filter",
"resource_type": "media-items",
"filters": {
"search": "keyword",
"author_filter": "Author Name",
"genre_filter": "Genre",
"sort": "title ASC"
}
}
```
**Validation:**
- `name` (string, required, max 100 chars) - Must be unique per user + resource type
- `resource_type` (string, required) - Must be valid resource type
- `filters` (object, required) - Key-value pairs of filter criteria
**Response:** Created filter object (HTTP 201)
**Error Responses:**
- 409 Conflict - Filter name already exists for this user + resource type
---
### PUT /api/saved-filters/:id
Update an existing saved filter.
**URL Parameters:**
- `id` (UUID, required) - Filter ID to update
**Request Body:** Same as POST
**Response:** Updated filter object
**Error Responses:**
- 404 Not Found - Filter doesn't exist or doesn't belong to user
- 409 Conflict - New name conflicts with existing filter
---
### DELETE /api/saved-filters/:id
Delete a saved filter.
**URL Parameters:**
- `id` (UUID, required) - Filter ID to delete
**Response:** 204 No Content (success)
**Error Responses:**
- 404 Not Found - Filter doesn't exist or doesn't belong to user