Data models

Explore schema definitions for BaseBook, BookWithAnalytics, Pagination, and Error response objects in the BookHub Publisher API.

Endpoint coverage for the hitCount field

The hitCount field records how many times buyers have retrieved a book’s details. For its full definition (type, constraints, read-only status), see Data models. The following table shows which endpoints include hitCount in their responses.

Endpoint	hitCount field in response?
GET /v2/books/{bookId}	Yes
GET /v2/books	No
POST /v2/books	No
DELETE /v2/books/{bookId}	No
PATCH /v2/books/{bookId}/finalize	No

BaseBook schema

This is the standard book object returned by the create, get, and list endpoints.

{
  "bookId": "string (read-only)",
  "title": "string (max 255 chars)",
  "author": "string (max 255 chars)",
  "description": "string (max 5000 chars)",
  "language": "string (BCP 47 language tag, e.g., en-US)",
  "publisher": "string (max 255 chars)",
  "publishedDate": "date (YYYY-MM-DD)",
  "isbn": "string (unique ISBN-10 or ISBN-13)",
  "price": "number (minimum 0.01)",
  "status": "enum (PENDING, ACTIVE, INACTIVE)",
  "coverImages": ["array of URLs (1-5 items)"],
  "genres": ["array of strings (1-5 items)"],
  "bookFormat": "enum (Paperback, Hardcover, eBook)",
  "createdDate": "datetime (ISO 8601, read-only)",
  "updatedDate": "datetime (ISO 8601, read-only)"
}

BaseBook example

A populated BaseBook object:

{
  "bookId": "123e4567-e89b-41d4-a716-426614174000",
  "title": "The Great Adventure",
  "author": "Jane Smith",
  "description": "An epic tale of courage and discovery",
  "language": "en-US",
  "publisher": "Adventure Books Inc",
  "publishedDate": "2024-03-15",
  "isbn": "978-0-1234-5678-9",
  "price": 24.99,
  "status": "ACTIVE",
  "coverImages": [
    "https://covers.bookhub.com/great-adventure-front.jpg"
  ],
  "genres": [
    "Fiction",
    "Adventure"
  ],
  "bookFormat": "Hardcover",
  "createdDate": "2024-12-25T10:30:00Z",
  "updatedDate": "2024-12-26T15:45:00Z"
}

BookWithAnalytics schema (v2 only)

This schema extends BaseBook with the following additional field:

  "hitCount": "integer (minimum 0, read-only)"

BookWithAnalytics example

For a populated BookWithAnalytics example, see the Get a specific book 200 response, which returns a BookWithAnalytics object, including the hitCount field.

Pagination schema

The pagination object used in list endpoints (e.g., GET /v2/books) to provide pagination details.

{
  "currentPage": "integer (minimum 1)",
  "totalPages": "integer (minimum 0)",
  "totalItems": "integer (minimum 0)",
  "itemsPerPage": "integer (1-100)"
}

Error response schema

The error response object returned when an API request fails.

The validation_context and provided_value fields use snake_case rather than camelCase. This is a known inconsistency in the v2 API that will be addressed in a future version. When parsing error responses, match these two fields by their exact snake_case keys.

{
  "status": "error",
  "message": "string",
  "errors": [
    {
      "field": "string",
      "error": "string",
      "description": "string",
      "validation_context": {
        "rule": "string",
        "constraint": "object",
        "provided_value": "string"
      }
    }
  ]
}

Next steps

Explore related topics:

Conceptual guides

• Using the hitCount field for analytics — Learn how hitCount tracks customer interest in specific titles.
• Pagination — Understand how pagination works in the BookHub Publisher API.

How-to guides

• Rank books by hitCount to find top performers — Use the hitCount field to rank books by buyer interest and flag your top performers.

Reference

• Release notes — Explore all changes in BookHub Publisher API v2.
• API endpoints — Provides additional information about the BookHub Publisher API v2 endpoints, including business rules.
• Code examples — Copy code samples for book creation, sorting by creation date, handling removed title sorting, and tracking performance with hitCount.

---