Add a bulk sorting endpoint

[bartimaeusnek]

API Endpoint or Feature

Add a bulk sorting endpoint for book contents to allow clients to reorder large books efficiently in a single request, instead of issuing many individual sort/update calls.

Endpoint: PUT /books/{id}/sort

Purpose: Accept a sort tree describing the desired order and hierarchy for chapters and pages within the specified book, and apply the changes atomically.

Proposed request body:

{
  "sort-tree": [
    {
      "id": 602,
      "sort": 0,
      "type": "page"
    },
    {
      "id": 27,
      "sort": 1,
      "type": "chapter"
    },
    {
      "id": 592,
      "sort": 0,
      "parentChapter": 27,
      "type": "page"
    }
  ]
}

Validation rules:

'sort' => [
    'sort-tree' => ['required', 'array', 'min:1'],
    'sort-tree.*.id' => ['required', 'integer'],
    'sort-tree.*.type' => ['required', 'in:chapter,page'],
    'sort-tree.*.sort' => ['required', 'integer'],
    'sort-tree.*.parentChapter' => ['integer', 'nullable']
    ]

This endpoint should perform a bulk update of sort order.

Use-Case

We built a BookStack integration inside our ticket system to manage documentation/books. When users reorder content in large books (many chapters/pages), the standard approach (multiple sequential sort/move operations or per-item updates) causes significant performance issues. (One customer's book usually takes ~3 minutes to be sorted.)

To address this, we implemented a single bulk sorting endpoint in a custom theme. The client sends one payload describing the complete target order (“sort-tree”) for chapters and pages.

In short: we need bulk sorting to make reordering large books reliable and fast within our integration.

Additional context

We have implemented this in a custom theme which we could provide if needed.