Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs: add library and media items API endpoints

Browse Source 
Phase 2 part 3: Split library and media item endpoints
- Libraries: get_visible_libraries, get_library, create_library, add_library_folder, set_library_visibility
- Media Items: list_media_items, get_media_item, search_media_items, filter_sort_media_items, update_media_item, delete_media_item
- Complete request/response examples for all endpoints
This commit is contained in:
john-okeefe
2026-02-02 08:51:43 -05:00
parent 52eb75cef7
commit 4b06983784
11 changed files with 601 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/libraries/add_library_folder.md
+51
View File
@@ -0,0 +1,51 @@
# Add Library Folder
Add a folder to an existing library (Admin only).
**Endpoint**: `POST /api/libraries/{library_id}/folders`
**Auth**: Required (Admin only)
**Content-Type**: `application/json`
## Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|-----------|-------------|
| library_id | string | Yes | Library UUID |
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| folder_path | string | Yes | Absolute path to folder |
### Example Request
```json
{
"folder_path": "/path/to/comics"
}
```
## Response (201 Created)
```json
{
"id": "uuid",
"library_id": "uuid",
"folder_path": "/path/to/comics",
"created_at": "2026-01-31T10:00:00Z"
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid folder path |
| 401 | Invalid or expired token |
| 403 | User is not an admin |
| 404 | Library not found |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->
docs/api/libraries/create_library.md
+49
View File
@@ -0,0 +1,49 @@
# Create Library
Create a new library (Admin only).
**Endpoint**: `POST /api/libraries`
**Auth**: Required (Admin only)
**Content-Type**: `application/json`
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| name | string | Yes | Library name |
| description | string | No | Library description |
| type | string | Yes | Library type (e.g., "ebooks", "comics", "audiobooks") |
### Example Request
```json
{
"name": "Comics Collection",
"description": "Digital comics",
"type": "comics"
}
```
## Response (201 Created)
```json
{
"id": "uuid",
"name": "Comics Collection",
"description": "Digital comics",
"type": "comics",
"created_at": "2026-01-31T10:00:00Z"
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid input data |
| 401 | Invalid or expired token |
| 403 | User is not an admin |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->
docs/api/libraries/get_library.md
+55
View File
@@ -0,0 +1,55 @@
# Get Library Details
Retrieve details of a specific library.
**Endpoint**: `GET /api/libraries/{library_id}`
**Auth**: Required
## Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|-----------|-------------|
| library_id | string | Yes | Library UUID |
## Request Headers
| Header | Type | Required | Description |
|--------|------|-----------|-------------|
| Authorization | string | Yes | Bearer token |
### Example Request
```http
GET /api/libraries/uuid-here
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
## Response (200 OK)
```json
{
"id": "uuid",
"name": "My Ebooks",
"description": "Ebook collection",
"type": "ebooks",
"folders": [
{
"id": "uuid",
"folder_path": "/path/to/ebooks"
}
],
"is_visible": true
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 401 | Invalid or expired token |
| 403 | User does not have access to this library |
| 404 | Library not found |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->
docs/api/libraries/get_visible_libraries.md
+45
View File
@@ -0,0 +1,45 @@
# Get Visible Libraries
Retrieve all libraries visible to the current user.
**Endpoint**: `GET /api/libraries/visible`
**Auth**: Required
## Request Headers
| Header | Type | Required | Description |
|--------|------|-----------|-------------|
| Authorization | string | Yes | Bearer token |
### Example Request
```http
GET /api/libraries/visible
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
## Response (200 OK)
```json
{
"libraries": [
{
"id": "uuid",
"name": "My Ebooks",
"description": "Ebook collection",
"type_name": "ebooks",
"is_visible": true
}
]
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 401 | Invalid or expired token |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->
docs/api/libraries/set_library_visibility.md
+48
View File
@@ -0,0 +1,48 @@
# Set Library Visibility
Set library visibility for a specific user (Admin only).
**Endpoint**: `POST /api/libraries/visibility`
**Auth**: Required (Admin only)
**Content-Type**: `application/json`
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| user_id | string | Yes | User UUID |
| library_id | string | Yes | Library UUID |
| is_visible | boolean | Yes | Whether library is visible to user |
### Example Request
```json
{
"user_id": "user-uuid",
"library_id": "library-uuid",
"is_visible": true
}
```
## Response (200 OK)
```json
{
"user_id": "user-uuid",
"library_id": "library-uuid",
"is_visible": true
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid input data |
| 401 | Invalid or expired token |
| 403 | User is not an admin |
| 404 | User or library not found |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->
docs/api/media-items/delete_media_item.md
+41
View File
@@ -0,0 +1,41 @@
# Delete Media Item
Delete a media item from the library (Admin only).
**Endpoint**: `DELETE /api/media-items/{media_id}`
**Auth**: Required (Admin only)
## Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|-----------|-------------|
| media_id | string | Yes | Media item UUID |
## Request Headers
| Header | Type | Required | Description |
|--------|------|-----------|-------------|
| Authorization | string | Yes | Bearer token |
### Example Request
```http
DELETE /api/media-items/uuid-here
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
## Response (204 No Content)
Media item deleted successfully.
## Error Responses
| Code | Description |
|------|-------------|
| 401 | Invalid or expired token |
| 403 | User is not an admin |
| 404 | Media item not found |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->
docs/api/media-items/filter_sort_media_items.md
+67
View File
@@ -0,0 +1,67 @@
# Filter & Sort Media Items
Filter and sort media items with advanced criteria.
**Endpoint**: `POST /api/media-items/filter`
**Auth**: Required
**Content-Type**: `application/json`
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| library_id | string | Yes | Library UUID |
| author_filter | string | No | Filter by author name |
| series_filter | string | No | Filter by series name |
| genre_filter | string | No | Filter by genre |
| year_min | integer | No | Minimum copyright year |
| year_max | integer | No | Maximum copyright year |
| has_cover | boolean | No | Filter by cover image existence |
| sort | string | No | Sort field and order (e.g., "title ASC", "created_at DESC") |
| limit | integer | No | Number of results (default 20) |
| offset | integer | No | Number to skip |
### Example Request
```json
{
"library_id": "uuid",
"author_filter": "Rowling",
"series_filter": "Harry Potter",
"genre_filter": "Fantasy",
"year_min": 1997,
"year_max": 2007,
"has_cover": true,
"sort": "title ASC",
"limit": 20,
"offset": 0
}
```
## Response (200 OK)
```json
{
"media_items": [
{
"id": "uuid",
"title": "Book Title",
"author": "Author Name",
"match_score": 0.95
}
],
"total": 7
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid filter parameters |
| 401 | Invalid or expired token |
| 403 | User does not have access to this library |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->
docs/api/media-items/get_media_item.md
+61
View File
@@ -0,0 +1,61 @@
# Get Media Item
Retrieve details of a specific media item.
**Endpoint**: `GET /api/media-items/{media_id}`
**Auth**: Required
## Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|-----------|-------------|
| media_id | string | Yes | Media item UUID |
## Request Headers
| Header | Type | Required | Description |
|--------|------|-----------|-------------|
| Authorization | string | Yes | Bearer token |
### Example Request
```http
GET /api/media-items/uuid-here
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
## Response (200 OK)
```json
{
"id": "uuid",
"library_id": "uuid",
"title": "Book Title",
"author": "Author Name",
"description": "Book description",
"file_path": "/path/to/book.epub",
"file_size": 1024000,
"mime_type": "application/epub+zip",
"cover_image_path": "/path/to/cover.jpg",
"series": "Series Name",
"series_number": 1,
"tags": "sci-fi, space opera",
"language": "en",
"page_count": 350,
"genre": "Science Fiction",
"copyright_year": 2023,
"created_at": "2026-01-31T10:00:00Z"
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 401 | Invalid or expired token |
| 403 | User does not have access to this media item |
| 404 | Media item not found |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->
docs/api/media-items/list_media_items.md
+68
View File
@@ -0,0 +1,68 @@
# List Media Items
Retrieve a paginated list of media items from a library.
**Endpoint**: `GET /api/media-items`
**Auth**: Required
## Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|-----------|-------------|
| library_id | string | Yes | Library UUID |
| limit | integer | No | Number of items to return (max 100, default 20) |
| offset | integer | No | Number of items to skip |
## Request Headers
| Header | Type | Required | Description |
|--------|------|-----------|-------------|
| Authorization | string | Yes | Bearer token |
### Example Request
```http
GET /api/media-items?library_id=uuid&limit=20&offset=0
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
## Response (200 OK)
```json
{
"media_items": [
{
"id": "uuid",
"library_id": "uuid",
"title": "Book Title",
"author": "Author Name",
"description": "Book description",
"file_path": "/path/to/book.epub",
"file_size": 1024000,
"mime_type": "application/epub+zip",
"cover_image_path": "/path/to/cover.jpg",
"series": "Series Name",
"series_number": 1,
"tags": "sci-fi, space opera",
"language": "en",
"page_count": 350,
"genre": "Science Fiction",
"copyright_year": 2023,
"created_at": "2026-01-31T10:00:00Z"
}
],
"total": 100
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid query parameters |
| 401 | Invalid or expired token |
| 403 | User does not have access to this library |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->
docs/api/media-items/search_media_items.md
+54
View File
@@ -0,0 +1,54 @@
# Search Media Items
Search for media items by title, author, or description.
**Endpoint**: `GET /api/media-items/search`
**Auth**: Required
## Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|-----------|-------------|
| q | string | Yes | Search query (minimum 2 characters) |
| limit | integer | No | Number of results (default 20) |
| offset | integer | No | Number to skip |
## Request Headers
| Header | Type | Required | Description |
|--------|------|-----------|-------------|
| Authorization | string | Yes | Bearer token |
### Example Request
```http
GET /api/media-items/search?q=Harry+Potter&limit=20&offset=0
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
## Response (200 OK)
```json
{
"results": [
{
"id": "uuid",
"title": "Book Title",
"author": "Author Name",
"match_score": 0.95
}
],
"total": 15
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid search query (too short) |
| 401 | Invalid or expired token |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->
docs/api/media-items/update_media_item.md
+62
View File
@@ -0,0 +1,62 @@
# Update Media Item
Update media item metadata (Admin only).
**Endpoint**: `PUT /api/media-items/{media_id}`
**Auth**: Required (Admin only)
**Content-Type**: `application/json`
## Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|-----------|-------------|
| media_id | string | Yes | Media item UUID |
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| title | string | No | Updated title |
| author | string | No | Updated author |
| description | string | No | Updated description |
| series | string | No | Series name |
| series_number | integer | No | Number in series |
### Example Request
```json
{
"title": "Updated Title",
"author": "Updated Author",
"description": "Updated description",
"series": "Series",
"series_number": 2
}
```
## Response (200 OK)
```json
{
"id": "uuid",
"title": "Updated Title",
"author": "Updated Author",
"description": "Updated description",
"series": "Series",
"series_number": 2,
"updated_at": "2026-01-31T10:00:00Z"
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid input data |
| 401 | Invalid or expired token |
| 403 | User is not an admin |
| 404 | Media item not found |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->