[PR #5280] [MERGED] Add book and chapter titles to search API results #6466

New Issue

OVERLORD · 2026-02-05T10:33:02+03:00

OVERLORD commented

2026-02-05 10:33:02 +03:00

📋 Pull Request Information

Original PR: https://github.com/BookStackApp/BookStack/pull/5280
Author: @rashadkhan359
Created: 10/21/2024
Status: ✅ Merged
Merged: 12/3/2024
Merged by: @ssddanbrown

Base: development ← Head: development

📝 Commits (3)

3e656ef Added include func for search api
90a8070 Eager loading for titles
f606711 respective book and chapter structure added.

📊 Changes

5 files changed (+150 additions, -75 deletions)

View changed files

📝 app/Api/ApiEntityListFormatter.php (+52 -2)
📝 app/Search/SearchApiController.php (+6 -6)
📝 dev/api/requests/search-all.http (+1 -1)
📝 dev/api/responses/search-all.json (+87 -62)
📝 tests/Api/SearchApiTest.php (+4 -4)

📄 Description

Purpose

Add the ability to include book and chapter titles in the /api/search endpoint results through an optional include parameter. This makes it easier for API consumers to show the full content hierarchy context for search results without additional API calls.

Closes

API Request #5140

Implementation

New Features

Added optional include parameter to /api/search endpoint
Supported include options:
- titles - Includes book_title and chapter_title for applicable entities
- tags - Include associated tags (existing functionality now controlled via include)

Multiple includes can be combined using comma separation.(if we want to extend on it.)

Changes

Added new ApiEntityListFormatter::withRelatedTitles(), ApiEntityListFormatter::loadRelatedTitles() and SearchApiController::parseIncludes() method.
Modified following existing methods:
- SearchApiController::$rules
- SearchApiController::all()
- ApiEntityListFormatter::format()
Added support for modular includes in search API controller
Added comprehensive tests for new functionality

Technical Details

Uses eager loading to prevent N+1 queries
Might not maintain backward compatibility (specifically since tags were already included by default but now we need to pass it in include for it to be included. This behavior if problematic can be altered easily.)
Follows existing BookStack API patterns
Includes full test coverage

Testing

New test cases cover:

Including/excluding titles
Multiple include combinations
Input validation
Edge cases

All existing tests pass without modification.

Documentation

The API documentation has been edited as well to cater to the new changes.

Example Request

GET /api/search?query=example&include=titles,tags

Example Response

{
  "data": [
    {
      "id": 84,
      "book_id": 1,
      "slug": "a-chapter-for-cats",
      "name": "A chapter for cats",
      "created_at": "2021-11-14T15:57:35.000000Z",
      "updated_at": "2021-11-14T15:57:35.000000Z",
      "type": "chapter",
      "url": "https://example.com/books/my-book/chapter/a-chapter-for-cats",
      "book_title": "Cats",
      "preview_html": {
        "name": "A chapter for <strong>cats</strong>",
        "content": "...once a bunch of <strong>cats</strong> named tony...behaviour of <strong>cats</strong> is unsuitable"
      },
      "tags": []
    },
    {
      "name": "The hows and whys of cats",
      "id": 396,
      "slug": "the-hows-and-whys-of-cats",
      "book_id": 1,
      "chapter_id": 75,
      "draft": false,
      "template": false,
      "created_at": "2021-05-15T16:28:10.000000Z",
      "updated_at": "2021-11-14T15:56:49.000000Z",
      "type": "page",
      "url": "https://example.com/books/my-book/page/the-hows-and-whys-of-cats",
      "book_title": "Cats",
      "chapter_title": "A chapter for cats",
      "preview_html": {
        "name": "The hows and whys of <strong>cats</strong>",
        "content": "...people ask why <strong>cats</strong>? but there are...the reason that <strong>cats</strong> are fast are due to..."
      },
      "tags": [
        {
          "name": "Animal",
          "value": "Cat",
          "order": 0
        },
        {
          "name": "Category",
          "value": "Top Content",
          "order": 0
        }
      ]
    },
    {
      "name": "How advanced are cats?",
      "id": 362,
      "slug": "how-advanced-are-cats",
      "book_id": 13,
      "chapter_id": 73,
      "draft": false,
      "template": false,
      "created_at": "2020-11-29T21:55:07.000000Z",
      "updated_at": "2021-11-14T16:02:39.000000Z",
      "type": "page",
      "url": "https://example.com/books/my-book/page/how-advanced-are-cats",
      "book_title": "Cats",
      "chapter_title": "A chapter for cats",
      "preview_html": {
        "name": "How advanced are <strong>cats</strong>?",
        "content": "<strong>cats</strong> are some of the most advanced animals in the world."
      },
      "tags": []
    }
  ],
  "total": 3
}

PS

This is my first-ever contribution to open source projects. I kindly ask for a thorough review, and I'm eager to improve upon any mistakes I may have made.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/BookStackApp/BookStack/pull/5280 **Author:** [@rashadkhan359](https://github.com/rashadkhan359) **Created:** 10/21/2024 **Status:** ✅ Merged **Merged:** 12/3/2024 **Merged by:** [@ssddanbrown](https://github.com/ssddanbrown) **Base:** `development` ← **Head:** `development` --- ### 📝 Commits (3) - [`3e656ef`](https://github.com/BookStackApp/BookStack/commit/3e656efb0088b180665e224a68adde061e86786b) Added include func for search api - [`90a8070`](https://github.com/BookStackApp/BookStack/commit/90a80705180d003a1e896bc307d3abc1720366dc) Eager loading for titles - [`f606711`](https://github.com/BookStackApp/BookStack/commit/f60671146379e76550ce81f7a8738f848ebc63de) respective book and chapter structure added. ### 📊 Changes **5 files changed** (+150 additions, -75 deletions) <details> <summary>View changed files</summary> 📝 `app/Api/ApiEntityListFormatter.php` (+52 -2) 📝 `app/Search/SearchApiController.php` (+6 -6) 📝 `dev/api/requests/search-all.http` (+1 -1) 📝 `dev/api/responses/search-all.json` (+87 -62) 📝 `tests/Api/SearchApiTest.php` (+4 -4) </details> ### 📄 Description ### Purpose Add the ability to include book and chapter titles in the `/api/search` endpoint results through an optional `include` parameter. This makes it easier for API consumers to show the full content hierarchy context for search results without additional API calls. ### Closes API Request #5140 ### Implementation #### New Features - Added optional `include` parameter to `/api/search` endpoint - Supported include options: - `titles` - Includes `book_title` and `chapter_title` for applicable entities - `tags` - Include associated tags (existing functionality now controlled via `include`) Multiple includes can be combined using comma separation.(if we want to extend on it.) #### Changes - Added new `ApiEntityListFormatter::withRelatedTitles()`, `ApiEntityListFormatter::loadRelatedTitles()` and `SearchApiController::parseIncludes()` method. - Modified following existing methods: - `SearchApiController::$rules` - `SearchApiController::all()` - `ApiEntityListFormatter::format()` - Added support for modular includes in search API controller - Added comprehensive tests for new functionality #### Technical Details - Uses eager loading to prevent N+1 queries - Might not maintain backward compatibility (specifically since tags were already included by default but now we need to pass it in `include` for it to be included. This behavior if problematic can be altered easily.) - Follows existing BookStack API patterns - Includes full test coverage #### Testing New test cases cover: - Including/excluding titles - Multiple include combinations - Input validation - Edge cases All existing tests pass without modification. ## Documentation The API documentation has been edited as well to cater to the new changes. ### Example Request `GET /api/search?query=example&include=titles,tags` ### Example Response ```json { "data": [ { "id": 84, "book_id": 1, "slug": "a-chapter-for-cats", "name": "A chapter for cats", "created_at": "2021-11-14T15:57:35.000000Z", "updated_at": "2021-11-14T15:57:35.000000Z", "type": "chapter", "url": "https://example.com/books/my-book/chapter/a-chapter-for-cats", "book_title": "Cats", "preview_html": { "name": "A chapter for cats", "content": "...once a bunch of cats named tony...behaviour of cats is unsuitable" }, "tags": [] }, { "name": "The hows and whys of cats", "id": 396, "slug": "the-hows-and-whys-of-cats", "book_id": 1, "chapter_id": 75, "draft": false, "template": false, "created_at": "2021-05-15T16:28:10.000000Z", "updated_at": "2021-11-14T15:56:49.000000Z", "type": "page", "url": "https://example.com/books/my-book/page/the-hows-and-whys-of-cats", "book_title": "Cats", "chapter_title": "A chapter for cats", "preview_html": { "name": "The hows and whys of cats", "content": "...people ask why cats? but there are...the reason that cats are fast are due to..." }, "tags": [ { "name": "Animal", "value": "Cat", "order": 0 }, { "name": "Category", "value": "Top Content", "order": 0 } ] }, { "name": "How advanced are cats?", "id": 362, "slug": "how-advanced-are-cats", "book_id": 13, "chapter_id": 73, "draft": false, "template": false, "created_at": "2020-11-29T21:55:07.000000Z", "updated_at": "2021-11-14T16:02:39.000000Z", "type": "page", "url": "https://example.com/books/my-book/page/how-advanced-are-cats", "book_title": "Cats", "chapter_title": "A chapter for cats", "preview_html": { "name": "How advanced are cats?", "content": "cats are some of the most advanced animals in the world." }, "tags": [] } ], "total": 3 } ``` ## PS This is my first-ever contribution to open source projects. I kindly ask for a thorough review, and I'm eager to improve upon any mistakes I may have made. --- 🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

OVERLORD added the pull-request label 2026-02-05 10:33:02 +03:00

OVERLORD closed this issue

2026-02-05 10:33:06 +03:00

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#6466