From 4b0698378439c2f51998b0687720fc2a3e289df1 Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Mon, 2 Feb 2026 08:51:43 -0500 Subject: [PATCH] docs: add library and media items API endpoints 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 --- docs/api/libraries/add_library_folder.md | 51 ++++++++++++++ docs/api/libraries/create_library.md | 49 +++++++++++++ docs/api/libraries/get_library.md | 55 +++++++++++++++ docs/api/libraries/get_visible_libraries.md | 45 ++++++++++++ docs/api/libraries/set_library_visibility.md | 48 +++++++++++++ docs/api/media-items/delete_media_item.md | 41 +++++++++++ .../media-items/filter_sort_media_items.md | 67 ++++++++++++++++++ docs/api/media-items/get_media_item.md | 61 +++++++++++++++++ docs/api/media-items/list_media_items.md | 68 +++++++++++++++++++ docs/api/media-items/search_media_items.md | 54 +++++++++++++++ docs/api/media-items/update_media_item.md | 62 +++++++++++++++++ 11 files changed, 601 insertions(+) create mode 100644 docs/api/libraries/add_library_folder.md create mode 100644 docs/api/libraries/create_library.md create mode 100644 docs/api/libraries/get_library.md create mode 100644 docs/api/libraries/get_visible_libraries.md create mode 100644 docs/api/libraries/set_library_visibility.md create mode 100644 docs/api/media-items/delete_media_item.md create mode 100644 docs/api/media-items/filter_sort_media_items.md create mode 100644 docs/api/media-items/get_media_item.md create mode 100644 docs/api/media-items/list_media_items.md create mode 100644 docs/api/media-items/search_media_items.md create mode 100644 docs/api/media-items/update_media_item.md diff --git a/docs/api/libraries/add_library_folder.md b/docs/api/libraries/add_library_folder.md new file mode 100644 index 0000000..1479113 --- /dev/null +++ b/docs/api/libraries/add_library_folder.md @@ -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 + + diff --git a/docs/api/libraries/create_library.md b/docs/api/libraries/create_library.md new file mode 100644 index 0000000..4f216fb --- /dev/null +++ b/docs/api/libraries/create_library.md @@ -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 + + diff --git a/docs/api/libraries/get_library.md b/docs/api/libraries/get_library.md new file mode 100644 index 0000000..100c893 --- /dev/null +++ b/docs/api/libraries/get_library.md @@ -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 + + diff --git a/docs/api/libraries/get_visible_libraries.md b/docs/api/libraries/get_visible_libraries.md new file mode 100644 index 0000000..468de5b --- /dev/null +++ b/docs/api/libraries/get_visible_libraries.md @@ -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 + + diff --git a/docs/api/libraries/set_library_visibility.md b/docs/api/libraries/set_library_visibility.md new file mode 100644 index 0000000..abe2ca0 --- /dev/null +++ b/docs/api/libraries/set_library_visibility.md @@ -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 + + diff --git a/docs/api/media-items/delete_media_item.md b/docs/api/media-items/delete_media_item.md new file mode 100644 index 0000000..d910dfb --- /dev/null +++ b/docs/api/media-items/delete_media_item.md @@ -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 + + diff --git a/docs/api/media-items/filter_sort_media_items.md b/docs/api/media-items/filter_sort_media_items.md new file mode 100644 index 0000000..6994f5d --- /dev/null +++ b/docs/api/media-items/filter_sort_media_items.md @@ -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 + + diff --git a/docs/api/media-items/get_media_item.md b/docs/api/media-items/get_media_item.md new file mode 100644 index 0000000..140a731 --- /dev/null +++ b/docs/api/media-items/get_media_item.md @@ -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 + + diff --git a/docs/api/media-items/list_media_items.md b/docs/api/media-items/list_media_items.md new file mode 100644 index 0000000..2e1c752 --- /dev/null +++ b/docs/api/media-items/list_media_items.md @@ -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 + + diff --git a/docs/api/media-items/search_media_items.md b/docs/api/media-items/search_media_items.md new file mode 100644 index 0000000..0de5d18 --- /dev/null +++ b/docs/api/media-items/search_media_items.md @@ -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 + + diff --git a/docs/api/media-items/update_media_item.md b/docs/api/media-items/update_media_item.md new file mode 100644 index 0000000..b2536e7 --- /dev/null +++ b/docs/api/media-items/update_media_item.md @@ -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 + +