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.
1.5 KiB
1.5 KiB
method, path, auth, area
| method | path | auth | area |
|---|---|---|---|
| GET | /api/media-items/facets | jwt | media-items |
Get Media Item Facets
Two modes, both returning small JSON objects:
- Facet values (primary):
?facet=<param>&library_id=<uuid>— lists the distinct values of a facet within one visible library. - Autocomplete counts:
?field=<key>&library_id=<uuid>— returns{"facets": {...}}value counts for dropdowns.
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 |