docs: refine cover image serving API documentation with static URL patterns

Update Bruno collection test documentation to reflect the new unified static-style
URL strategy for cover images and media downloads.

Changes:
- Update cover image endpoint from /api/covers/{id} to /uploads/library-{id}/{path}
- Update download endpoint from /api/media-items/{id}/download to /uploads/library-{id}/{path}
- Document JWT authentication for static endpoints (same as API endpoints)
- Add clarification that resolved URLs come from API responses
- Update status codes to reflect new endpoint behavior
- Rename 'Download Media Item.yml' to 'EPUB Download.yml' for clarity

This documentation aligns with the unified URL strategy where all file access
goes through a consistent /uploads/library-{id}/ pattern with JWT-based
authentication, eliminating separate API endpoints for file serving.
This commit is contained in:
2026-02-26 21:42:08 -05:00
parent 749cbd91ff
commit b834cbe40a
+24 -16
View File
@@ -524,17 +524,18 @@ info:
seq: 1 seq: 1
http: http:
method: GET method: GET
url: '{{base_url}}/api/covers/{{media_item_id}}' url: '{{base_url}}/uploads/library-{{library_id}}/path/to/cover.jpg'
auth: none auth: none
docs: |- docs: |-
## Get Cover Image ## Get Cover Image
Retrieve the cover image for a media item. Requires authentication. Retrieve the cover image for a media item via authenticated static-style URL.
Uses JWT authentication (same as API endpoints).
**Method:** GET **Method:** GET
**Endpoint:** /api/covers/{id} **Endpoint:** /uploads/library-{id}/{path}
**Authentication:** Bearer token required **Authentication:** Bearer token required
@@ -542,16 +543,19 @@ docs: |-
**Status Codes:** **Status Codes:**
- 200: Success - returns image - 200: Success - returns image
- 400: Invalid media item ID - 401: Unauthorized (missing/invalid JWT)
- 401: Unauthorized - 404: File not found
- 404: Media item not found or cover doesn't exist
**Note:** The actual path would come from the API response which provides
the resolved URL. This test is a template showing the URL format.
Note: Uses `media_item_id` from environment variables. vars:
library_id: ""
``` ```
#### File: `bruno/media-items/Download Media Item.yml` (Update existing) #### File: `bruno/media-items/EPUB Download.yml` (Update existing)
Update the existing file to document that it now handles relative paths: Update the existing file to note that downloads now work through the same `/uploads/library-{id}/` endpoint:
```yaml ```yaml
info: info:
@@ -560,17 +564,18 @@ info:
seq: 1 seq: 1
http: http:
method: GET method: GET
url: '{{base_url}}/api/media-items/{{media_item_id}}/download' url: '{{base_url}}/uploads/library-{{library_id}}/path/to/book.epub'
auth: none auth: none
docs: |- docs: |-
## Download Media Item ## Download Media Item
Download a media item file (EPUB, PDF, CBZ, etc.) from Bookhoard server. Download a media item file (EPUB, PDF, CBZ, etc.) via authenticated static-style URL.
Uses JWT authentication (same as API endpoints).
**Method:** GET **Method:** GET
**Endpoint:** /api/media-items/{id}/download **Endpoint:** /uploads/library-{id}/{path}
**Authentication:** Bearer token required **Authentication:** Bearer token required
@@ -584,11 +589,14 @@ docs: |-
**Status Codes:** **Status Codes:**
- 200: Success - returns file - 200: Success - returns file
- 400: Invalid media item ID - 401: Unauthorized (missing/invalid JWT)
- 401: Unauthorized - 404: File not found
- 404: Media item not found or file doesn't exist on disk
**Note:** The actual path would come from the API response which provides
the resolved URL. This test shows the URL format.
Note: Uses `media_item_id` from environment variables. vars:
library_id: ""
``` ```
--- ---