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

docs(api): add new endpoint documentation

Browse Source 
- Add create_media_item.md for media item creation API

- Add delete_rating.md for rating deletion endpoint

- Add update_rating.md for rating update endpoint
This commit is contained in:
john-okeefe
2026-02-08 13:33:09 -05:00
parent adc7acbe0f
commit c437528522
3 changed files with 189 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/developer/api/media-items/create_media_item.md
+94
View File
@@ -0,0 +1,94 @@
# Create Media Item
Create a new media item (Admin only).
**Endpoint**: `POST /api/media-items`
**Auth**: Required (Admin only)
**Content-Type**: `application/json`
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| library_id | string (UUID) | Yes | Library UUID to add the media item to |
| title | string | Yes | Media item title (1-500 characters) |
| author | string | No | Author name |
| isbn | string | No | ISBN number |
| description | string | No | Description or summary |
| file_path | string | Yes | Path to the media file |
| file_size | integer | Yes | Size of the file in bytes |
| mime_type | string | Yes | MIME type of the file |
| cover_image_path | string | No | Path to the cover image |
| series | string | No | Series name |
| series_number | integer | No | Number in the series |
| tags | array of strings | No | Tags (auto-normalized) |
| asin | string | No | Amazon ASIN |
| date_published | string | No | Publication date |
| publisher | string | No | Publisher name |
| contributors | array of strings | No | Contributors (auto-normalized) |
## Tag/Contributor Normalization
Tags and contributors are automatically normalized:
- **Tags**: Titlecased, punctuation preserved, case-insensitive deduplication
- **Contributors**: Original casing and punctuation preserved, case-insensitive deduplication
- **Search fields**: Auto-generated for case-insensitive search
### Example Request
```json
{
"library_id": "550e8400-e29b-41d4-a716-446655440000",
"title": "Example Book Title",
"author": "Jane Doe",
"isbn": "978-0-123456-78-9",
"description": "A great book about technology",
"file_path": "/library/books/example.epub",
"file_size": 1048576,
"mime_type": "application/epub+zip",
"series": "Tech Series",
"series_number": 1,
"tags": ["science-fiction", "technology", "ACME CORP."],
"publisher": "O'Reilly Media",
"contributors": ["John Smith", "ACME CORP."]
}
```
## Response (201 Created)
```json
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"library_id": "550e8400-e29b-41d4-a716-446655440000",
"title": "Example Book Title",
"author": "Jane Doe",
"isbn": "978-0-123456-78-9",
"description": "A great book about technology",
"file_path": "/library/books/example.epub",
"file_size": 1048576,
"mime_type": "application/epub+zip",
"series": "Tech Series",
"series_number": 1,
"tags": ["Science-Fiction", "Technology", "ACME CORP."],
"tags_search": ["science fiction", "technology", "acme corp"],
"publisher": "O'Reilly Media",
"contributors": ["John Smith", "ACME CORP."],
"contributors_search": ["john smith", "acme corp"],
"created_at": "2026-01-31T10:00:00Z",
"updated_at": "2026-01-31T10:00:00Z"
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid request data |
| 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/developer/api/ratings/delete_rating.md
+38
View File
@@ -0,0 +1,38 @@
# Delete Rating
Delete the current user's rating for a media item.
**Endpoint**: `DELETE /api/media-items/{media_id}/rating`
**Auth**: Required
## Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|-----------|-------------|
| media_id | string | Yes | Media item UUID |
### Example Request
```http
DELETE /api/media-items/550e8400-e29b-41d4-a716-446655440000/rating
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
## Response (200 OK)
```json
{
"message": "Rating deleted successfully"
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 401 | Invalid or expired token |
| 404 | Media item or rating not found |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->
docs/developer/api/ratings/update_rating.md
+57
View File
@@ -0,0 +1,57 @@
# Update Rating
Update an existing rating for a media item.
**Endpoint**: `PUT /api/media-items/{media_id}/rating`
**Auth**: Required
**Content-Type**: `application/json`
## Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|-----------|-------------|
| media_id | string | Yes | Media item UUID |
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| rating | integer | Yes | Rating value (1-10 scale) |
| review | string | No | Optional review text |
**Rating Scale**: 1-10 (odd numbers = half-stars: 1=0.5★, 2=1★, 3=1.5★, ..., 9=4.5★, 10=5★)
### Example Request
```json
{
"rating": 8,
"review": "Great book! Very enjoyable read."
}
```
## Response (200 OK)
```json
{
"id": "uuid",
"media_item_id": "uuid",
"user_id": "uuid",
"rating": 8,
"review": "Great book! Very enjoyable read.",
"created_at": "2026-01-31T10:00:00Z",
"updated_at": "2026-01-31T11:00:00Z"
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid request data |
| 401 | Invalid or expired token |
| 404 | Media item or rating not found |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->