Library management

Browse, search, bookmark, and review books across your entire ReadRealm library. Your reading lists and progress stay in sync on Android, iOS, and the web.

The ReadRealm library gives you access to a large catalog of books sourced from Open Library and Project Gutenberg. You can search by keyword, browse by genre, save books to your reading list, and leave reviews — all of which stay in sync across every device you use.

Search

Find books by title or author across the Open Library catalog.

Browse by genre

Explore curated shelves of books organized by subject.

Bookmarks

Save books to your personal reading list with one tap.

Reviews

Rate books from 1–5 stars and write a comment.

Searching for books

Use the search endpoint to find books by any keyword — title, author name, or topic. Results come directly from the Open Library catalog and include the cover image, author, publication year, and page count.

GET /book/search?q={query}

Example — search for “Moby Dick”:

curl "http://localhost:3000/book/search?q=moby+dick"

[
  {
    "title": "Moby Dick",
    "author": "Herman Melville",
    "publicationDate": 1851,
    "numOfPages": 654,
    "coverImage": "https://covers.openlibrary.org/b/id/8231856-M.jpg"
  }
]

Search returns up to 12 results by default.

Browsing by genre

Browse books organized by subject using the genre endpoint. Results stream to your client as they are fetched, so the first books appear immediately without waiting for the full page to load.

GET /book/genre/{genre}?offset=0&limit=10

Parameter	Type	Default	Max	Description
genre	string	—	—	Subject name, e.g. science-fiction
offset	number	0	—	Pagination offset
limit	number	10	50	Number of results per page

Passing all as the genre returns no results. Use a specific subject name such as mystery, romance, or history.

Results are cached for 15 minutes, so repeated requests for the same genre are fast.

Bookmarks

Bookmark any book to add it to your personal reading list. Bookmarking the same book a second time removes it — the endpoint works as a toggle.

PUT /book/bookmark

Request body:

{
  "userId": "user_abc123",
  "book": {
    "id": 12345,
    "title": "Moby Dick",
    "author": "Herman Melville",
    "publicationDate": 1851,
    "numOfPages": 654,
    "coverImage": "https://covers.openlibrary.org/b/id/8231856-M.jpg",
    "genre": "Fiction"
  }
}

If the book does not yet exist in the ReadRealm catalog, it is created automatically before the bookmark is saved.

Retrieve your bookmarked books:

GET /book/bookmarks/{userId}

This returns the full list of books the user has bookmarked.

Cross-platform sync

Bookmarks are stored centrally and associated with your user ID, so they are immediately available on every device — Android, iOS, and the web — without any manual sync step.

Your bookmarks appear the same whether you open ReadRealm on your phone at home or on a desktop at work.

Reviews

Leave a rating and comment on any book in the catalog. Ratings are on a 1–5 scale. Each review is also analyzed for sentiment automatically — positive, negative, or neutral — so you can see the general mood of reader reactions at a glance.

Submit a review:

POST /book/reviews/{bookId}

Request body:

{
  "userId": "user_abc123",
  "bookId": 12345,
  "rating": 4,
  "comment": "A gripping read that keeps you hooked until the final page."
}

Get reviews for a book:

GET /book/reviews/{bookId}

Get all reviews you have written:

GET /book/user-reviews/{userId}

User reviews include an emotion field (positive, negative, or neutral) derived from sentiment analysis of your comment text.

Typical workflow

1. Search or browse

   Use search to find a specific book by title or author, or open a genre shelf to explore books by subject.

2. View book details

   Open a book to see its cover, description, author, publication year, and reader reviews.

   GET /book/details/{id}
   
3. Bookmark the book

   Tap the bookmark icon to save the book to your reading list. The book is instantly available from the bookmarks section on all your devices.

4. Read the book

   Open the EPUB reader to start reading. See EPUB reading for details on the reading experience.

5. Leave a review

   After reading, submit a rating and comment. Your review contributes to the book’s average rating shown to all readers.

AI-powered recommendations

When you open a book’s detail page, ReadRealm uses Google Generative AI (Gemini) to generate a summary of the book’s content. This summary gives you a quick five-line overview before you decide to read it. See AI-powered insights for more.