Books API

Endpoints for searching books, retrieving book details, and checking availability.

Search Books

Search for books by title, author, or ISBN.

GET /books?q={query}

Authentication

Optional (Bearer token)

Query Parameters

• q (required) - Search query (title, author, or ISBN)
• limit (optional) - Number of results (1-50, default: 20)
• offset (optional) - Pagination offset (default: 0)

Response

{
  "items": [
    {
      "id": "bb0e8400-e29b-41d4-a716-446655440006",
      "isbn": "9780316769174",
      "title": "The Catcher in the Rye",
      "authors": ["J.D. Salinger"],
      "publisher": "Little, Brown and Company",
      "publishedDate": "1991-05-01",
      "description": "The hero-narrator of The Catcher in the Rye is an ancient child of sixteen...",
      "coverUrl": "https://covers.bookwish.app/9780316769174.jpg",
      "pageCount": 277,
      "categories": ["Fiction", "Classics"],
      "averageRating": 4.5,
      "totalReviews": 1248
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Errors

• 400 BadRequest - Missing or invalid query parameter
• 500 InternalServerError - Server error

Example

curl "https://api.bookwish.app/books?q=catcher%20in%20the%20rye&limit=10"

Get Book by ID

Get detailed information about a specific book by its ID.

GET /books/:id

Authentication

Optional (Bearer token)

Path Parameters

• id - Book ID

Response

{
  "id": "bb0e8400-e29b-41d4-a716-446655440006",
  "isbn": "9780316769174",
  "isbn13": "9780316769174",
  "title": "The Catcher in the Rye",
  "authors": ["J.D. Salinger"],
  "publisher": "Little, Brown and Company",
  "publishedDate": "1991-05-01",
  "description": "The hero-narrator of The Catcher in the Rye is an ancient child of sixteen, a schoolboy who has flunked out of prep school and is now wandering through New York City. He has a grudge against everything but his little sister, Phoebe, and he feels alienated by all the phoniness in the world around him.",
  "coverUrl": "https://covers.bookwish.app/9780316769174.jpg",
  "pageCount": 277,
  "language": "en",
  "categories": ["Fiction", "Classics", "Coming of Age"],
  "averageRating": 4.5,
  "totalReviews": 1248,
  "totalLines": 342,
  "createdAt": "2024-01-05T09:00:00Z",
  "updatedAt": "2024-01-20T15:30:00Z"
}

Errors

• 404 NotFound - Book not found
• 500 InternalServerError - Server error

Example

curl "https://api.bookwish.app/books/bb0e8400-e29b-41d4-a716-446655440006"

Get Book by ISBN

Get detailed information about a specific book by its ISBN.

GET /books/isbn/:isbn

Authentication

Optional (Bearer token)

Path Parameters

• isbn - ISBN-10 or ISBN-13

Response

{
  "id": "bb0e8400-e29b-41d4-a716-446655440006",
  "isbn": "9780316769174",
  "isbn13": "9780316769174",
  "title": "The Catcher in the Rye",
  "authors": ["J.D. Salinger"],
  "publisher": "Little, Brown and Company",
  "publishedDate": "1991-05-01",
  "description": "The hero-narrator of The Catcher in the Rye is an ancient child of sixteen...",
  "coverUrl": "https://covers.bookwish.app/9780316769174.jpg",
  "pageCount": 277,
  "language": "en",
  "categories": ["Fiction", "Classics"],
  "averageRating": 4.5,
  "totalReviews": 1248,
  "createdAt": "2024-01-05T09:00:00Z"
}

Errors

• 400 BadRequest - Invalid ISBN format
• 404 NotFound - Book not found
• 500 InternalServerError - Server error

Example

curl "https://api.bookwish.app/books/isbn/9780316769174"

Check Book Availability

Check if a book is available at local stores.

GET /books/:id/availability

Authentication

Required (Bearer token)

Path Parameters

• id - Book ID

Query Parameters

• latitude (optional) - User's latitude for location-based search
• longitude (optional) - User's longitude for location-based search
• radius (optional) - Search radius in miles (default: 25)

Response

{
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "availability": [
    {
      "storeId": "660e8400-e29b-41d4-a716-446655440001",
      "storeName": "Downtown Books",
      "storeSlug": "downtown-books",
      "quantity": 3,
      "priceCents": 1599,
      "condition": "new",
      "distance": 2.4,
      "addressLine1": "123 Main St",
      "city": "Springfield",
      "state": "IL"
    },
    {
      "storeId": "660e8400-e29b-41d4-a716-446655440002",
      "storeName": "Book Corner",
      "storeSlug": "book-corner",
      "quantity": 1,
      "priceCents": 899,
      "condition": "used_like_new",
      "distance": 5.7,
      "addressLine1": "456 Oak Ave",
      "city": "Springfield",
      "state": "IL"
    }
  ]
}

Errors

• 401 Unauthorized - Not authenticated
• 404 NotFound - Book not found
• 500 InternalServerError - Server error

Example

curl "https://api.bookwish.app/books/bb0e8400-e29b-41d4-a716-446655440006/availability?latitude=39.7817&longitude=-89.6501&radius=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Book Lines

Get social posts (lines) about a specific book.

GET /books/:id/lines

Authentication

Optional (Bearer token)

Path Parameters

• id - Book ID

Query Parameters

• cursor (optional) - Pagination cursor
• limit (optional) - Number of items (1-100, default: 20)

Response

{
  "items": [
    {
      "id": "aa0e8400-e29b-41d4-a716-446655440005",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
      "user": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "username": "johndoe",
        "displayName": "John Doe",
        "avatarUrl": "https://cdn.bookwish.app/avatars/johndoe.jpg"
      },
      "content": "This book completely changed my perspective on teenage rebellion!",
      "likeCount": 42,
      "replyCount": 8,
      "isLiked": false,
      "createdAt": "2024-01-20T14:30:00Z"
    }
  ],
  "nextCursor": "cc0e8400-e29b-41d4-a716-446655440007"
}

Errors

• 400 BadRequest - Invalid parameters
• 404 NotFound - Book not found
• 500 InternalServerError - Server error

Example

curl "https://api.bookwish.app/books/bb0e8400-e29b-41d4-a716-446655440006/lines?limit=10"

Get Book Reviews

Get reviews for a specific book with average rating.

GET /books/:id/reviews

Authentication

Optional (Bearer token)

Path Parameters

• id - Book ID

Query Parameters

• cursor (optional) - Pagination cursor
• limit (optional) - Number of items (1-100, default: 20)
• sort (optional) - Sort order: recent or rating (default: recent)

Response

{
  "items": [
    {
      "id": "dd0e8400-e29b-41d4-a716-446655440008",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
      "user": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "username": "johndoe",
        "displayName": "John Doe",
        "avatarUrl": "https://cdn.bookwish.app/avatars/johndoe.jpg",
        "tier": "premium"
      },
      "rating": 5,
      "content": "An absolute masterpiece of modern literature. Salinger's portrayal of teenage angst is timeless.",
      "likeCount": 15,
      "isLiked": false,
      "createdAt": "2024-01-18T11:00:00Z",
      "updatedAt": "2024-01-18T11:00:00Z"
    }
  ],
  "nextCursor": "ee0e8400-e29b-41d4-a716-446655440009",
  "averageRating": 4.5,
  "totalReviews": 1248
}

Errors

• 400 BadRequest - Invalid parameters
• 404 NotFound - Book not found
• 500 InternalServerError - Server error

Example

curl "https://api.bookwish.app/books/bb0e8400-e29b-41d4-a716-446655440006/reviews?sort=rating&limit=10"

Book Object Fields

Field	Type	Description
id	string	Unique book identifier (UUID)
isbn	string	ISBN-10 or ISBN-13
isbn13	string	ISBN-13 format
title	string	Book title
authors	string[]	List of author names
publisher	string	Publisher name
publishedDate	string	Publication date (ISO 8601)
description	string	Book description/synopsis
coverUrl	string	URL to cover image
pageCount	number	Number of pages
language	string	Language code (ISO 639-1)
categories	string[]	Book categories/genres
averageRating	number	Average user rating (0-5)
totalReviews	number	Total number of reviews
totalLines	number	Total number of social posts
createdAt	string	Creation timestamp (ISO 8601)
updatedAt	string	Last update timestamp (ISO 8601)