library-rest
List books with optional filtering and pagination.
GET
/booksReturns books matching the given filters, ordered by id, together with the total number of matches (before pagination is applied) in meta.total. All filters are optional and combine with logical AND; omitting every filter returns the full catalog, one page at a time.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| authorId | query | string | Restrict results to books written by this author. | |
| status | query | string | Restrict results to books in this availability status. A book's availability. borrowed means it is out on an open loan. Allowed values: available, borrowed | |
| q | query | string | Case-insensitive substring match against the book title. | |
| offset | query | integer | Number of matching books to skip, for pagination. Must not be negative. | |
| limit | query | integer | Maximum number of books to return. Omit or use 0 to return every remaining match after offset. Must not be negative. |
Responses
200 The page of books matching the filter.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
| data | array of object | yes | |
| authorId | string | yes | The id of the Author who wrote this book. |
| createdAt | string (date-time) | yes | When the book record was created. |
| id | string | yes | Unique identifier assigned by the server, prefixed with bk_. |
| isbn | string | yes | The book's ISBN. Must be unique across the catalog. |
| publishedYear | integer | yes | The year the book was first published. Must be between 1450 and next year. |
| status | string | yes | A book's availability. borrowed means it is out on an open loan. Allowed values: available, borrowed |
| title | string | yes | The book's display title, 1–200 characters. |
| updatedAt | string (date-time) | yes | When the book record was last modified. |
| meta | object | yes | Response metadata attached to every successful response. |
| requestId | string | yes | Correlation id for this request, echoed from the X-Request-Id request header or generated if absent. Useful for tracing a request across logs. |
| total | integer | Total number of matches before pagination was applied. Present only on paginated list responses (currently GET /books). |
Errors
| Code | Message | Description |
|---|---|---|
| 400 | A query parameter could not be parsed (e.g. offset is not an integer). | |
| 401 | The request is missing a valid Authorization: Bearer <token> header. | |
| 422 | A filter value failed validation (e.g. an unknown status, or a negative offset/limit). | |
| 500 | An unexpected error occurred. The response never leaks internal error details. |
Response example
{
"data": [
{
"authorId": "authorId_784",
"createdAt": "createdAt_137",
"id": "id_661",
"isbn": "isbn_827",
"publishedYear": 317,
"status": "borrowed",
"title": "title_602",
"updatedAt": "updatedAt_573"
}
],
"meta": {
"requestId": "requestId_93",
"total": 193
}
}