List Books (v1.0.0)

Get all books with advanced filtering and pagination

GET Book

Overview

Get all books in the system with advanced filtering, sorting, and pagination support. This endpoint retrieves a collection of book aggregates from the Catalog bounded context, applying domain filters and returning DTOs that comply with our anti-corruption layer patterns.

The endpoint respects the read model separation in our CQRS implementation, using dedicated read models optimized for query performance. Results can be filtered by various domain attributes including genre, author, and publication status.

Each book in the returned collection contains core domain properties while maintaining a clear separation between entity identity and value objects according to DDD principles.

Architecture

GET (/api/v1/books)

Query Parameters

ParameterTypeRequiredDefaultDescription
pageIndexintegerNo1The page number to retrieve (1-based)
pageSizeintegerNo10Number of items per page
orderBystringNoNameProperty to sort results by. Valid values: Name, OriginalPrice, DiscountPrice, Status
isDescendingbooleanNofalseWhether to sort results in descending order
searchstringNonullSearch term to filter books by (uses semantic search)
minPricedecimalNonullMinimum price filter
maxPricedecimalNonullMaximum price filter
categoryIdarray[Guid]NonullFilter by specific category IDs
publisherIdarray[Guid]NonullFilter by specific publisher IDs
authorIdsarray[Guid]NonullFilter by specific author IDs

Examples Usage

Basic

Example Request
curl -X GET "https://api.bookworm.com/api/v1/books"

With Pagination

Example Request
curl -X GET "https://api.bookworm.com/api/v1/books?pageIndex=2&pageSize=20"

With Search and Filters

Example Request
curl -X GET "https://api.bookworm.com/api/v1/books?search=fantasy&minPrice=10&maxPrice=50&categoryId=123e4567-e89b-12d3-a456-426614174000"

With Sorting

Example Request
curl -X GET "https://api.bookworm.com/api/v1/books?orderBy=Price.OriginalPrice&isDescending=true"

Responses

400 Bad Request

When the request parameters are invalid:

200 OK

Returns a paged result containing the filtered books:

Example Response

200 OK
{
  "pageIndex": 1,
  "pageSize": 10,
  "totalItems": 20,
  "totalPages": 2,
  "hasNextPage": true,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "0195e692-600b-715e-a17b-b3a8faf4ed07",
      "name": "The Great Gatsby",
      "description": "A classic novel by F. Scott Fitzgerald.",
      "imageUrl": "URL_ADDRESS.com/great-gatsby.jpg",
      "price": 10.99,
      "discountPrice": 9.99,
      "status": "InStock",
      "authors": [
        {
          "id": "0195e692-600b-7290-a47f-982b9d7f15f3",
          "name": "F. Scott Fitzgerald"
        },
        {
          "id": "0195e692-600b-7d32-99b0-ae7abd82a863",
          "name": "John Smith"
        }
      ],
      "category": {
        "id": "0195e692-600b-7424-a426-dac7227720fe",
        "name": "Fiction"
      },
      "publisher": {
        "id": "0195e692-600b-78b3-9b7f-3e342d9f2815",
        "name": "Scribner"
      },
      "averageRating": 4.5,
      "totalReviews": 100,
    }
  ]
}

Notes

  • The endpoint uses semantic search when a search term is provided
  • All filters can be combined to create complex queries
  • Results are always paginated to ensure optimal performance
  • The response includes metadata about the total number of items and pages
  • Books are returned with their related entities (authors, category, publisher) included