Migrate to BookHub Publisher API v2

Update your code to use BookHub Publisher API v2’s new features.

This guide walks you through migrating your code from BookHub Publisher API v1 to v2. It covers the two breaking changes in v2: the hitCount field addition and the removal of title sorting. For the complete list of changes, see Breaking changes. For a complete overview, see Release notes.

Prerequisites

Before you begin, ensure you meet the following prerequisites:

• Familiarity with BookHub Publisher API v1.
• Access to your codebase that integrates with the BookHub Publisher API.
• A valid JWT for authentication.

Step 1: Update base URLs

Start by updating all API URLs in your code from v1 to v2. For example:

Before (v1)

https://api.bookhub.com/api/v1/books

After (v2)

https://api.bookhub.com/api/v2/books

Step 2: Handle the hitCount field

Use the hitCount field on individual books to track views. Replace separate analytics API calls with this field in your existing code for retrieving book details. For details on hitCount data type, range, and availability, see Get a specific book.

Before (v1)

response = requests.get(f"{BASE_URL}/v1/books/{book_id}")
book = response.json()['data']
# book has no hitCount field

After (v2)

response = requests.get(f"{BASE_URL}/v2/books/{book_id}")
book = response.json()['data']
hit_count = book.get('hitCount', 0)  # New field available
print(f"This book has been viewed {hit_count} times")

Step 3: Replace title sorting

v2 removes the sort=title parameter. Replace it with sort=createdDate:

Before (v1)

# Sort by title in ascending order
response = requests.get(f"{BASE_URL}/v1/books?sort=title&order=asc")

After (v2)

# Sort by creation date in descending order
response = requests.get(f"{BASE_URL}/v2/books?sort=createdDate&order=desc")

If your code still passes sort=title, v2 returns a 400 error. Handle it by falling back to sort=createdDate. See Migrate away from title sorting for the full error response and a retry pattern.

Step 4: Test your migration

After making these changes, test your code to ensure it works correctly with BookHub Publisher API v2. Verify that the hitCount field is accessible and that sorting behaves as expected. You should see 201, 200, and an integer hitCount.

1. Send a Create book request and verify:

   • The responsereturns 201 Created with a bookId.
   • The Finalize book request returns 200 OK and updates the book status to ACTIVE.
   • The hitCount field is included and updates correctly for each retrieved book.
   • The date sorting functions as expected.

For example:

import requests

BASE_URL = "https://api.bookhub.com/api"
TOKEN = "YOUR_JWT_TOKEN"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

# Step 1. Create a book
create_response = requests.post(
    f"{BASE_URL}/v2/books",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "title": "My New Book",
        "author": "John Doe",
        "description": "A new biography from a well-known author",
        "language": "en-US",
        "publisher": "My Publishing House",
        "publishedDate": "2026-03-15",
        "isbn": "978-3-16-148410-0",
        "price": 24.99,
        "coverImages": ["https://example.com/cover.jpg"],
        "genres": ["Fiction", "Adventure"],
        "bookFormat": "Hardcover"
    }
)
print(f"Create: {create_response.status_code}")
book_id = create_response.json()['data']['bookId']

# Step 2. Finalize the book
finalize_response = requests.patch(
    f"{BASE_URL}/v2/books/{book_id}/finalize",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"notes": "Migration test"}
)
print(f"Finalize: {finalize_response.status_code}")

# Step 3. Retrieve the book and verify hitCount
get_response = requests.get(
    f"{BASE_URL}/v2/books/{book_id}",
    headers=HEADERS
)
book = get_response.json()['data']
print(f"Status: {book['status']}")
print(f"hitCount: {book.get('hitCount', 'field not found')}")

# Step 4. Verify date sorting works
list_response = requests.get(
    f"{BASE_URL}/v2/books",
    headers=HEADERS,
    params={"sort": "createdDate", "order": "desc"}
)
print(f"List books: {list_response.status_code}")

Next steps

Explore related topics:

Quickstart guide

• Quickstart guide — Get up and running with the BookHub Publisher API v2 in minutes.

Conceptual guides

• Using the hitCount field for analytics — Understand the hitCount field in the BookHub Publisher API v2.

How-to guides

• Migrate away from title sorting — Update your code to remove title sorting in BookHub Publisher API v2.
• Rank books by hitCount to find top performers — Use the hitCount field to rank books by buyer interest and flag your top performers.
• Monitor rate limits — Implement best practices for handling API rate limits.

Reference

• Release notes — Explore all changes in BookHub Publisher API v2.
• Breaking changes in v2 — Highlights important information about breaking changes in the BookHub Publisher API.
• Track high-performing books with hitCount — Learn how to use the hitCount field in PHP.

---