> ## Documentation Index
> Fetch the complete documentation index at: https://galejames.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://galejames.mintlify.site/how-to-guides/how-to-guides-migrate-away-from-title-sorting.md).

### 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:

```http theme={null}
GET /v1/books?sort=title&order=asc
```

#### ❌ Invalid request

In v2, this won't work:

```http theme={null}
GET /v2/books?sort=title&order=asc
```

**Returns a `400` error**

```json theme={null}
{
  "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:

```http theme={null}
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](https://galejames.mintlify.site/reference/reference-data-models.md#error-response-schema) for the full error response schema.

## Next steps

Explore related topics:

### Conceptual guides

* [Using the `hitCount` field for analytics](https://galejames.mintlify.site/conceptual-guides/conceptual-guides-hitcount-analytics) — Learn how `hitCount` tracks customer interest in specific titles.
* [Pagination](https://galejames.mintlify.site/conceptual-guides/conceptual-guides-pagination.mdx) — Understand how pagination works in the BookHub Publisher API.

### How-to guides

* [Migrate to BookHub Publisher API v2](https://galejames.mintlify.site/how-to-guides/how-to-guides-migrate-bookhub.md) — Update your code to use BookHub Publisher API v2’s new features.
* [Migrate away from title sorting](https://galejames.mintlify.site/how-to-guides/how-to-guides-migrate-away-from-title-sorting.md) — Update your code to remove title sorting in BookHub Publisher API v2.

### Reference

* [Release notes](https://galejames.mintlify.site/reference/reference-release-notes.md) — Explore all changes in BookHub Publisher API v2.
* [API endpoints](https://galejames.mintlify.site/reference/reference-api-endpoints.md) — Provides additional information about the BookHub Publisher API v2 endpoints, including business rules.
* [Code examples](https://galejames.mintlify.site/reference/reference-code-examples.md) — Copy code samples for book creation, sorting by creation date, handling removed title sorting, and tracking performance with `hitCount`.

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.