Skip to main content
GET
/
books
List Books
curl --request GET \
  --url https://api.example.com/books
{
  "content": [
    {
      "isbn": "<string>",
      "title": "<string>",
      "author": {
        "author.id": 123,
        "author.name": "<string>",
        "author.age": 123
      },
      "stock": 123,
      "coverImage": "<string>"
    }
  ],
  "pageable": {
    "pageNumber": 123,
    "pageSize": 123,
    "sort": {},
    "offset": 123,
    "paged": true,
    "unpaged": true
  },
  "totalPages": 123,
  "totalElements": 123,
  "last": true,
  "first": true,
  "size": 123,
  "number": 123,
  "numberOfElements": 123,
  "empty": true
}
Retrieve a paginated list of all books in the library.

​
Authentication

This endpoint requires HTTP Basic Authentication.

​
Query Parameters

​
page
integer
default:"0"
The page number to retrieve (zero-indexed).
​
size
integer
default:"20"
The number of items per page.
​
sort
string
Sort criteria in the format: property,direction. For example: title,asc or stock,desc. Multiple sort parameters can be provided.

​
Response

The response is a paginated object containing an array of books and pagination metadata.
​
content
array
Array of book objects.
​
isbn
string
The ISBN of the book.
​
title
string
The title of the book.
​
author
object
The author information.
​
author.id
integer
The unique identifier of the author.
​
author.name
string
The name of the author.
​
author.age
integer
The age of the author.
​
stock
integer
The number of copies available in stock.
​
coverImage
string
URL or path to the book’s cover image. Only included if set.
​
pageable
object
Pagination information about the current request.
​
pageNumber
integer
The current page number (zero-indexed).
​
pageSize
integer
The number of items per page.
​
sort
object
Sort information.
​
offset
integer
The offset of the first item in the current page.
​
paged
boolean
Whether the response is paginated.
​
unpaged
boolean
Whether the response is unpaginated.
​
totalPages
integer
The total number of pages available.
​
totalElements
integer
The total number of books across all pages.
​
last
boolean
Whether this is the last page.
​
first
boolean
Whether this is the first page.
​
size
integer
The size of the current page.
​
number
integer
The current page number (zero-indexed).
​
numberOfElements
integer
The number of elements in the current page.
​
empty
boolean
Whether the current page is empty.

​
Status Codes

  • 200 OK: Successfully retrieved the list of books
  • 401 Unauthorized: Authentication credentials are missing or invalid

​
Example Request

curl -X GET "https://api.example.com/books?page=0&size=10&sort=title,asc" \
  -u username:password

​
Example Response

{
  "content": [
    {
      "isbn": "978-0-7475-3269-9",
      "title": "Harry Potter and the Philosopher Stone",
      "author": {
        "id": 1,
        "name": "J.K. Rowling",
        "age": 58
      },
      "stock": 15,
      "coverImage": "https://example.com/covers/hp1.jpg"
    },
    {
      "isbn": "978-0-4510-5271-5",
      "title": "The Great Gatsby",
      "author": {
        "id": 2,
        "name": "F. Scott Fitzgerald",
        "age": 44
      },
      "stock": 8
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10,
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    },
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "totalPages": 5,
  "totalElements": 42,
  "last": false,
  "first": true,
  "size": 10,
  "number": 0,
  "numberOfElements": 10,
  "empty": false
}

​
Notes

  • The default page size is 20 items if not specified.
  • Pages are zero-indexed, so the first page is page=0.
  • You can sort by any book property such as isbn, title, or stock.
  • Multiple sort parameters can be provided to sort by multiple fields.

Build docs developers (and LLMs) love

Get started for freeTalk to us