Breaking changes

Highlights important information about breaking changes in the BookHub Publisher API.

This section highlights the breaking changes in v2 of the BookHub Publisher API. If you use v1, review these changes for a smoother migration.

Title sorting removed (breaking change)

The GET /v2/books endpoint no longer supports sorting results by title using sort=title. Use sort=createdDate instead. For migration steps, see Migrate away from title sorting.

v1 vs. v2 behavior

The sort parameter in the GET all books endpoint has changed. In v1, you could sort by title. In v2, sorting is supported only by createdDate.

In v1, this worked:

GET /v1/books?sort=title&order=asc

❌ Invalid request

In v2, this won’t work:

GET /v2/books?sort=title&order=asc

Returns a 400 error

{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "sort",
      "error": "INVALID_VALUE",
      "description": "sort must be createdDate. Title sorting was removed in v2.",
      "validation_context": {
        "rule": "allowed_values",
        "constraint": {
          "allowed": ["createdDate"]
        },
        "provided_value": "title"
      }
    }
  ]
}

✅ Valid request

In v2, use this instead:

GET /v2/books?sort=createdDate&order=desc

Available sort options in v2

If you use order without sort, the default sort=createdDate applies and order defaults to desc. Pagination parameters (page, limit) and filtering (status) are unchanged from v1.

The sort parameter now accepts only one value:

• createdDate (default: newest first)

The order parameter still works:

• asc: Ascending (oldest to newest)
• desc: Descending (newest to oldest, default)

Idempotency-Key header

The POST /v2/books endpoint now requires an Idempotency-Key header to prevent duplicate book creation on retries.

409 Conflict responses

Duplicate ISBNs are rejected with 409 Conflict. v1 did not enforce ISBN uniqueness.

Known issues

The BookHub Publisher API v2 has the following known issues that will be addressed in future versions:

validation_context and provided_value use snake_case

The validation_context and provided_value fields in the error response schema use snake_case rather than the camelCase convention used throughout the rest of the API. This inconsistency will be corrected in a future version. Plan your error handling code accordingly.

See Data models for the full error response schema.

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

• Migrate to BookHub Publisher API v2 — Update your code to use BookHub Publisher API v2’s new features.
• Migrate away from title sorting — Update your code to remove title sorting in BookHub Publisher API v2.

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.

---