NotAShelf
273d0244aa
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: Ia8426a63a50d07a6cec2b104951d58eb6a6a6964
207 lines
4.5 KiB
Markdown
Vendored
207 lines
4.5 KiB
Markdown
Vendored
# Books
|
|
|
|
Book metadata, series, authors, and reading progress
|
|
|
|
## Endpoints
|
|
|
|
### GET /api/v1/books
|
|
|
|
List all books with optional search filters
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
| ----------- | ----- | -------- | ------------------- |
|
|
| `isbn` | query | No | Filter by ISBN |
|
|
| `author` | query | No | Filter by author |
|
|
| `series` | query | No | Filter by series |
|
|
| `publisher` | query | No | Filter by publisher |
|
|
| `language` | query | No | Filter by language |
|
|
| `offset` | query | No | Pagination offset |
|
|
| `limit` | query | No | Pagination limit |
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
| ------ | --------------------- |
|
|
| 200 | List of books |
|
|
| 401 | Unauthorized |
|
|
| 500 | Internal server error |
|
|
|
|
---
|
|
|
|
### GET /api/v1/books/authors
|
|
|
|
List all authors with book counts
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
| -------- | ----- | -------- | ----------------- |
|
|
| `offset` | query | No | Pagination offset |
|
|
| `limit` | query | No | Pagination limit |
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
| ------ | ------------------------ |
|
|
| 200 | Authors with book counts |
|
|
| 401 | Unauthorized |
|
|
|
|
---
|
|
|
|
### GET /api/v1/books/authors/{name}/books
|
|
|
|
Get books by a specific author
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
| -------- | ----- | -------- | ----------------- |
|
|
| `name` | path | Yes | Author name |
|
|
| `offset` | query | No | Pagination offset |
|
|
| `limit` | query | No | Pagination limit |
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
| ------ | --------------- |
|
|
| 200 | Books by author |
|
|
| 401 | Unauthorized |
|
|
|
|
---
|
|
|
|
### GET /api/v1/books/reading-list
|
|
|
|
Get user's reading list
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
| -------- | ----- | -------- | ------------------------------------------------------------------------------ |
|
|
| `status` | query | No | Filter by reading status. Valid values: to_read, reading, completed, abandoned |
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
| ------ | ------------ |
|
|
| 200 | Reading list |
|
|
| 401 | Unauthorized |
|
|
|
|
---
|
|
|
|
### GET /api/v1/books/series
|
|
|
|
List all series with book counts
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
| ------ | -------------------------- |
|
|
| 200 | List of series with counts |
|
|
| 401 | Unauthorized |
|
|
|
|
---
|
|
|
|
### GET /api/v1/books/series/{name}
|
|
|
|
Get books in a specific series
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
| ------ | ---- | -------- | ----------- |
|
|
| `name` | path | Yes | Series name |
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
| ------ | --------------- |
|
|
| 200 | Books in series |
|
|
| 401 | Unauthorized |
|
|
|
|
---
|
|
|
|
### GET /api/v1/books/{id}/metadata
|
|
|
|
Get book metadata by media ID
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
| ---- | ---- | -------- | ------------- |
|
|
| `id` | path | Yes | Media item ID |
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
| ------ | ------------- |
|
|
| 200 | Book metadata |
|
|
| 401 | Unauthorized |
|
|
| 404 | Not found |
|
|
|
|
---
|
|
|
|
### GET /api/v1/books/{id}/progress
|
|
|
|
Get reading progress for a book
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
| ---- | ---- | -------- | ------------- |
|
|
| `id` | path | Yes | Media item ID |
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
| ------ | ---------------- |
|
|
| 200 | Reading progress |
|
|
| 401 | Unauthorized |
|
|
| 404 | Not found |
|
|
|
|
---
|
|
|
|
### PUT /api/v1/books/{id}/progress
|
|
|
|
Update reading progress for a book
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
| ---- | ---- | -------- | ------------- |
|
|
| `id` | path | Yes | Media item ID |
|
|
|
|
#### Request Body
|
|
|
|
`Content-Type: application/json`
|
|
|
|
See `docs/api/openapi.json` for the full schema.
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
| ------ | ---------------- |
|
|
| 204 | Progress updated |
|
|
| 400 | Bad request |
|
|
| 401 | Unauthorized |
|
|
|
|
---
|