John O'Keefe
cc893f758e
Every API doc that declares frontmatter (method/path/auth/area) is now checked by a unit test against three sources of truth: 1. Route registration: internal/router/*.go is parsed the way echo resolves it (group prefixes concatenate; scanner.go's parameterized groups seeded). Doc paths that no longer exist fail. (This is the check that would have caught the /api/api/admin/hash-conflicts split.) 2. Auth: frontmatter auth label must match the middleware chain (none|jwt|jwt+admin|device-token|optional-jwt). 3. Shapes: internal/docs/schema.go registry — example-request decoded with unknown fields DISALLOWED (typo guard), required-by-validate fields must appear (staleness guard), example-response top-level key set compared both directions against the marshaled handler type (or a RawMessage pin for hand-built map responses). Five collections docs are the pilots with real handler shapes; notable corrections they pin: update returns 201 (not 200), list excludes smart collections unless include_auto=true, rule priority is 1-10 higher-wins (docs claimed 1=highest), created_at is Go time.String() not RFC3339, hide_finished/show_up_next toggles documented. CollectionResponse hoisted out of GetCollections/GetBookCollections as CollectionSummary / BookCollectionSummary so the registry can pin real types. The gate fails on missing registry entries by design — that is the maintenance contract. Known pre-existing (not this commit): vet copy-lock warnings in media.go.
75 lines
1.9 KiB
Markdown
75 lines
1.9 KiB
Markdown
---
|
|
method: GET
|
|
path: /api/collections/:id
|
|
auth: jwt
|
|
area: collections
|
|
---
|
|
<!-- source: internal/handlers/collections.go:243 CollectionHandler.GetCollection -->
|
|
|
|
# Get Collection
|
|
|
|
Returns one collection with its books and, for smart collections, the
|
|
computed Up Next entries.
|
|
|
|
## Example request
|
|
|
|
```text
|
|
GET /api/collections/550e8400-e29b-41d4-a716-446655440000
|
|
```
|
|
|
|
## Example response
|
|
|
|
```json example-response
|
|
{
|
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"user_id": "8f14e45f-ceea-467f-a429-0b21bfc0b1a2",
|
|
"name": "To Read",
|
|
"description": "Books I want to read soon",
|
|
"color": "#00FF00",
|
|
"icon": "📖",
|
|
"auto_assign_rules": null,
|
|
"view_settings": { "kobo": { "view_mode": "grid" } },
|
|
"books": [],
|
|
"book_count": 0,
|
|
"is_smart": false,
|
|
"up_next": [],
|
|
"created_at": "2026-10-24 13:57:01.81234 +0000 UTC"
|
|
}
|
|
```
|
|
|
|
`created_at` uses Go's `time.String()` format, not RFC3339. `books` and
|
|
`up_next` are book-card arrays; `up_next` items carry
|
|
`id`, `title`, `author`, `cover`, `format`, `progress`.
|
|
|
|
## Query parameters
|
|
|
|
| Param | Type | Notes |
|
|
| ----- | ---- | ----- |
|
|
| library_id | uuid | optional; scopes items/counts to one library (invalid values are rejected with 400) |
|
|
|
|
## Response fields
|
|
|
|
| Field | Type | Notes |
|
|
| ----- | ---- | ----- |
|
|
| id | string (uuid) | |
|
|
| user_id | string (uuid) | owner |
|
|
| name | string | |
|
|
| description | string | |
|
|
| color | string | |
|
|
| icon | string | |
|
|
| auto_assign_rules | array \| null | |
|
|
| view_settings | object | |
|
|
| books | array | book cards in this collection |
|
|
| book_count | number | length of `books` |
|
|
| is_smart | boolean | |
|
|
| up_next | array | smart collections only: computed next-up entries |
|
|
| created_at | string | |
|
|
|
|
## Errors
|
|
|
|
| Status | Body | When |
|
|
| ------ | ---- | ---- |
|
|
| 400 | `{"error": "invalid collection id"}` / `{"error": "invalid library_id"}` | malformed id(s) |
|
|
| 404 | `{"error": "collection not found"}` | no such collection |
|
|
| 500 | `{"error": "..."}` | unexpected server error |
|