library-rest

List books with optional filtering and pagination.

GET/books

Returns 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

NameInTypeRequiredDescription
authorIdquerystringRestrict results to books written by this author.
statusquerystringRestrict results to books in this availability status. A book's availability. borrowed means it is out on an open loan. Allowed values: available, borrowed
qquerystringCase-insensitive substring match against the book title.
offsetqueryintegerNumber of matching books to skip, for pagination. Must not be negative.
limitqueryintegerMaximum 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

FieldTypeRequiredDescription
dataarray of objectyes
authorIdstringyesThe id of the Author who wrote this book.
createdAtstring (date-time)yesWhen the book record was created.
idstringyesUnique identifier assigned by the server, prefixed with bk_.
isbnstringyesThe book's ISBN. Must be unique across the catalog.
publishedYearintegeryesThe year the book was first published. Must be between 1450 and next year.
statusstringyesA book's availability. borrowed means it is out on an open loan. Allowed values: available, borrowed
titlestringyesThe book's display title, 1–200 characters.
updatedAtstring (date-time)yesWhen the book record was last modified.
metaobjectyesResponse metadata attached to every successful response.
requestIdstringyesCorrelation id for this request, echoed from the X-Request-Id request header or generated if absent. Useful for tracing a request across logs.
totalintegerTotal number of matches before pagination was applied. Present only on paginated list responses (currently GET /books).

Errors

CodeMessageDescription
400A query parameter could not be parsed (e.g. offset is not an integer).
401The request is missing a valid Authorization: Bearer <token> header.
422A filter value failed validation (e.g. an unknown status, or a negative offset/limit).
500An 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
  }
}