docs(api): add new endpoint documentation

- 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
2026-02-08 13:33:09 -05:00
parent adc7acbe0f
commit c437528522
3 changed files with 189 additions and 0 deletions
@@ -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 -->