John O'Keefe
6fc501b35a
Stats docs written handler/service-first (summary/this-week/book-stats
new; library-usage frontmatter'd — its body was already accurate).
Registry: 4 entries on services.UserSummaryStats/WeekSummaryStats/
LibraryUsageStats/BookStats. Family-lens note: library-usage 403s an
explicit library_id outside the visible set (431fec0 rule).
UNVERIFIED sweep (7 -> 0), each resolved against the handler:
- device-usage takes NO date params; popular-books takes only ?limit
(the 'standard analytics date-range params' claim was wrong)
- link_book media_item_id: no validate tag but service-always-written
- push_stats book-ref field set documented (uuid/sha256/title/authors)
- filter_count: confirmed ParseMediaSearchParams machinery + 400 on bad
filter + 403 visibility
- facets values element shape pinned: {value, display?, count}
- get_config: dynamic key set IS the contract (reworded, no marker)
make test 9/9.
52 lines
1.5 KiB
Markdown
52 lines
1.5 KiB
Markdown
---
|
|
method: GET
|
|
path: /api/media-items/facets
|
|
auth: jwt
|
|
area: media-items
|
|
---
|
|
<!-- source: internal/handlers/media.go:2532 MediaHandler.GetFacets -->
|
|
|
|
# Get Media Item Facets
|
|
|
|
Two modes, both returning small JSON objects:
|
|
|
|
1. **Facet values** (primary): `?facet=<param>&library_id=<uuid>` — lists the
|
|
distinct values of a facet within one visible library.
|
|
2. **Autocomplete counts**: `?field=<key>&library_id=<uuid>` — returns
|
|
`{"facets": {...}}` value counts for dropdowns.
|
|
|
|
## Example response
|
|
|
|
```json example-response
|
|
{
|
|
"facet": "author",
|
|
"values": [
|
|
{
|
|
"value": "George Orwell"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
`values` elements are `{value, display?, count}` rows (`FacetValue`):
|
|
`value` is the raw value that rides the filter param, `display` is the
|
|
prettified form when it differs (language codes → names; absent means the
|
|
client shows `value`), `count` is the number of matching items.
|
|
|
|
## Query parameters
|
|
|
|
| Param | Type | Notes |
|
|
| ----- | ---- | ----- |
|
|
| facet | string | facet param name; requires `library_id` |
|
|
| field | string | registry field key (autocomplete mode) |
|
|
| library_id | uuid | required for facet mode; must be visible to the requester |
|
|
| limit | number | caps facet values |
|
|
|
|
## Errors
|
|
|
|
| Status | Body | When |
|
|
| ------ | ---- | ---- |
|
|
| 400 | `{"error": "library_id is required"}` / `{"error": "unknown facet: ..."}` / `{"error": "facet does not list values: ..."}` / `{"error": "invalid library_id"}` | bad params |
|
|
| 403 | `{"error": "library not visible"}` | family lens |
|
|
| 500 | `{"error": "..."}` | unexpected server error |
|