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
http:
method: GET
url: '{{base_url}}/api/covers/{{media_item_id}}'
url: '{{base_url}}/uploads/library-{{library_id}}/path/to/cover.jpg'
auth: none
docs: |-
## 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
**Endpoint:** /api/covers/{id}
**Endpoint:** /uploads/library-{id}/{path}
**Authentication:** Bearer token required
@@ -542,16 +543,19 @@ docs: |-
**Status Codes:**
- 200: Success - returns image
- 400: Invalid media item ID
- 401: Unauthorized
- 404: Media item not found or cover doesn't exist
- 401: Unauthorized (missing/invalid JWT)
- 404: File not found
**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
info:
@@ -560,17 +564,18 @@ info:
seq: 1
http:
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
docs: |-
## 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
**Endpoint:** /api/media-items/{id}/download
**Endpoint:** /uploads/library-{id}/{path}
**Authentication:** Bearer token required
@@ -584,11 +589,14 @@ docs: |-
**Status Codes:**
- 200: Success - returns file
- 400: Invalid media item ID
- 401: Unauthorized
- 404: Media item not found or file doesn't exist on disk
- 401: Unauthorized (missing/invalid JWT)
- 404: File not found
**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: ""
```
---