docs: update Bruno collection with unified search endpoints
- Update Search All Libraries.yml with expanded documentation - Add Fuzzy Author Filter.yml (author_filter=asimov example) - Add Fuzzy Genre Filter.yml (genre_filter=scifi example) - Add Combined Search and Filters.yml (q=foundation&author_filter=asimov example) - Add Exact Match With Quotes.yml (q="Foundation and Empire" example) - Add Field Values Search - Authors.yml (autocomplete dropdown example) - Add Field Values Search - Genres.yml (autocomplete dropdown example) - Add Field Values Search - Series.yml (autocomplete dropdown example) - Add Field Values Search - Languages.yml (autocomplete dropdown example) - Remove deprecated Filter Media Items.yml scenario All files include request config, params, examples, expected responses, and success criteria for API interaction during development.
This commit is contained in:
@@ -8,9 +8,53 @@ http:
|
||||
url: "{{base_url}}/api/media-items/search"
|
||||
params:
|
||||
- name: q
|
||||
value: "harry"
|
||||
value: "foundation"
|
||||
type: query
|
||||
disabled: false
|
||||
- name: library_id
|
||||
value: "{{library_id}}"
|
||||
type: query
|
||||
disabled: false
|
||||
- name: author_filter
|
||||
value: ""
|
||||
type: query
|
||||
disabled: true
|
||||
- name: series_filter
|
||||
value: ""
|
||||
type: query
|
||||
disabled: true
|
||||
- name: genre_filter
|
||||
value: ""
|
||||
type: query
|
||||
disabled: true
|
||||
- name: language_filter
|
||||
value: ""
|
||||
type: query
|
||||
disabled: true
|
||||
- name: year_min
|
||||
value: ""
|
||||
type: query
|
||||
disabled: true
|
||||
- name: year_max
|
||||
value: ""
|
||||
type: query
|
||||
disabled: true
|
||||
- name: has_cover
|
||||
value: ""
|
||||
type: query
|
||||
disabled: true
|
||||
- name: sort
|
||||
value: "title ASC"
|
||||
type: query
|
||||
disabled: true
|
||||
- name: limit
|
||||
value: "50"
|
||||
type: query
|
||||
disabled: true
|
||||
- name: offset
|
||||
value: "0"
|
||||
type: query
|
||||
disabled: true
|
||||
auth: inherit
|
||||
|
||||
settings:
|
||||
@@ -22,7 +66,7 @@ settings:
|
||||
docs: |-
|
||||
## Search All Libraries
|
||||
|
||||
Searches for media items across all libraries without filtering.
|
||||
Searches for media items using the unified search endpoint. Supports fuzzy search, exact match, and filtering.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
@@ -30,23 +74,148 @@ docs: |-
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Query Parameters:**
|
||||
- `q` (string, required): Search query (minimum 2 characters)
|
||||
## Query Parameters
|
||||
|
||||
**Response:** HTTP 200 (OK)
|
||||
### Search Parameters:
|
||||
- `q` (string, optional): Global search query
|
||||
- Fuzzy matching by default (tolerates typos)
|
||||
- Exact match with quotes: `"\"exact phrase\""`
|
||||
- Searches: title, author, series, tags, contributors
|
||||
- Example: `q=foundation` (fuzzy), `q="\"Foundation and Empire\""` (exact)
|
||||
|
||||
### Filter Parameters (All Fuzzy Except Years/Booleans):
|
||||
- `author_filter` (string, optional): Fuzzy match author field
|
||||
- Example: `author_filter=asimov` matches "Asimov, Isaac"
|
||||
|
||||
- `series_filter` (string, optional): Fuzzy match series field
|
||||
- Example: `series_filter=harry` matches "Harry Potter"
|
||||
|
||||
- `genre_filter` (string, optional): Fuzzy match genre field
|
||||
- Example: `genre_filter=scifi` matches "Sci-Fi", "Science Fiction"
|
||||
|
||||
- `language_filter` (string, optional): Fuzzy match language field
|
||||
- Example: `language_filter=eng` matches "English", "eng"
|
||||
|
||||
- `year_min` (integer, optional): Minimum copyright year (exact range)
|
||||
- Example: `year_min=2000`
|
||||
|
||||
- `year_max` (integer, optional): Maximum copyright year (exact range)
|
||||
- Example: `year_max=2020`
|
||||
|
||||
- `has_cover` (boolean, optional): Filter by cover image presence
|
||||
- Values: `true`, `false`, or empty (all)
|
||||
- Example: `has_cover=true`
|
||||
|
||||
### Pagination Parameters:
|
||||
- `limit` (integer, optional): Number of results (default: 50, max: 200)
|
||||
- Example: `limit=100`
|
||||
|
||||
- `offset` (integer, optional): Number of results to skip (for pagination)
|
||||
- Example: `offset=50`
|
||||
|
||||
- `sort` (string, optional): Sort order (default: relevance DESC, title ASC)
|
||||
- Options:
|
||||
- `title ASC` - Title A-Z
|
||||
- `title DESC` - Title Z-A
|
||||
- `author ASC` - Author A-Z
|
||||
- `author DESC` - Author Z-A
|
||||
- `created_at ASC` - Date added oldest first
|
||||
- `created_at DESC` - Date added newest first
|
||||
- `page_count ASC` - Page count low to high
|
||||
- `page_count DESC` - Page count high to low
|
||||
- Example: `sort=author ASC`
|
||||
|
||||
## How Fuzzy Matching Works
|
||||
|
||||
**Text Filters (author, series, genre, language):**
|
||||
- Uses PostgreSQL pg_trgm word_similarity()
|
||||
- Threshold: 0.3 (30% similarity)
|
||||
- Handles typos: "azimov" → "Asimov"
|
||||
- Handles partial matches: "scifi" → "Sci-Fi"
|
||||
- Case-insensitive
|
||||
|
||||
**Search Query (q parameter):**
|
||||
- **Fuzzy (default):** Matches similar words across title, author, series, tags
|
||||
- `q=foundation` → "Foundation", "Foundations", "The Foundation"
|
||||
- **Exact (with quotes):** Must match the exact phrase
|
||||
- `q="\"Foundation and Empire\""` → Only "Foundation and Empire"
|
||||
|
||||
## Response
|
||||
|
||||
**HTTP 200 (OK):**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"title": "Harry Potter and the Sorcerer's Stone",
|
||||
"author": "J.K. Rowling",
|
||||
"title": "Foundation",
|
||||
"author": "Asimov, Isaac",
|
||||
"series": "Foundation",
|
||||
"genre": "Sci-Fi",
|
||||
"language": "English",
|
||||
"copyright_year": 1951,
|
||||
"page_count": 255,
|
||||
"cover_image_path": "/path/to/cover.jpg",
|
||||
"library_id": "uuid",
|
||||
"library_name": "E-Books"
|
||||
"library_name": "E-Books",
|
||||
"library_type_name": "ebooks"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Success Criteria:**
|
||||
**HTTP 404 (Not Found):**
|
||||
```json
|
||||
{
|
||||
"error": "no results found",
|
||||
"query": "foundation",
|
||||
"results": []
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
**1. Simple search:**
|
||||
```
|
||||
GET /api/media-items/search?q=harry&library_id={uuid}
|
||||
```
|
||||
Returns books matching "harry" in title/author/series
|
||||
|
||||
**2. Fuzzy author filter:**
|
||||
```
|
||||
GET /api/media-items/search?author_filter=asimov&library_id={uuid}
|
||||
```
|
||||
Returns books by authors similar to "asimov"
|
||||
|
||||
**3. Combined search + filters:**
|
||||
```
|
||||
GET /api/media-items/search?q=foundation&author_filter=asimov&genre_filter=scifi&library_id={uuid}
|
||||
```
|
||||
Returns "foundation" books by "asimov" in "scifi" genre
|
||||
|
||||
**4. Exact match with quotes:**
|
||||
```
|
||||
GET /api/media-items/search?q="\"Foundation and Empire\""&library_id={uuid}
|
||||
```
|
||||
Returns only exact title match
|
||||
|
||||
**5. Year range + sorting:**
|
||||
```
|
||||
GET /api/media-items/search?year_min=2000&year_max=2020&sort=created_at DESC&library_id={uuid}
|
||||
```
|
||||
Returns books from 2000-2020 sorted by newest first
|
||||
|
||||
**6. Boolean filter:**
|
||||
```
|
||||
GET /api/media-items/search?has_cover=true&library_id={uuid}
|
||||
```
|
||||
Returns only books that have cover images
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Status: 200
|
||||
- Returns array of media items from all libraries
|
||||
- Results match search query
|
||||
- Returns array of media items matching all filters
|
||||
- Results sorted by:
|
||||
1. Relevance score (when searching with `q`)
|
||||
2. User-specified sort parameter
|
||||
3. Title (final fallback)
|
||||
- Pagination works correctly with limit/offset
|
||||
|
||||
|
||||
Reference in New Issue
Block a user