[PR #1826] [MERGED] Baseline API Implementation #5902

New Issue

OVERLORD · 2026-02-05T10:19:59+03:00

OVERLORD commented

2026-02-05 10:19:59 +03:00

📋 Pull Request Information

Original PR: https://github.com/BookStackApp/BookStack/pull/1826
Author: @ssddanbrown
Created: 12/28/2019
Status: ✅ Merged
Merged: 1/18/2020
Merged by: @ssddanbrown

Base: master ← Head: api_origins

📝 Commits (10+)

04137e7 Started core API route work
d336ba6 Started work on API token controls
dccb279 Built out interfaces & endpoints for API token managment
832fbd6 Added testing coverage to user API token interfaces
692fc46 Removed token 'client' text, avoid confusion w/ oAuth
2cfa373 Fixed some empty-expiry conditions of token ui flows
3de55ee Linked new API token system into middleware
349b462 Extracted API auth into guard
6f1b88a Change email confirmation from own middle to trait
3d11cba Added testing coverage to API token auth

📊 Changes

71 files changed (+2556 additions, -99 deletions)

View changed files

📝 .env.example.complete (+6 -0)
➕ app/Api/ApiDocsGenerator.php (+125 -0)
➕ app/Api/ApiToken.php (+31 -0)
➕ app/Api/ApiTokenGuard.php (+166 -0)
➕ app/Api/ListingResponseBuilder.php (+135 -0)
📝 app/Auth/Role.php (+1 -1)
📝 app/Auth/User.php (+15 -6)
📝 app/Auth/UserRepo.php (+1 -0)
➕ app/Config/api.php (+23 -0)
📝 app/Config/auth.php (+1 -3)
📝 app/Entities/Book.php (+2 -1)
➕ app/Exceptions/ApiAuthException.php (+7 -0)
📝 app/Exceptions/Handler.php (+42 -0)
➕ app/Exceptions/UnauthorizedException.php (+17 -0)
➕ app/Http/Controllers/Api/ApiController.php (+30 -0)
➕ app/Http/Controllers/Api/ApiDocsController.php (+47 -0)
➕ app/Http/Controllers/Api/BooksApiController.php (+101 -0)
➕ app/Http/Controllers/UserApiTokenController.php (+139 -0)
📝 app/Http/Controllers/UserController.php (+8 -6)
📝 app/Http/Kernel.php (+4 -7)

...and 51 more files

📄 Description

Create some level of baseline API implementation.
This will cover just the basic CRUD book endpoints and nothing more.

The purpose of this is to get a basic implementation in place for feedback to ensure it's sensible before scaling it out to many other endpoints.

TODO

Implement Overview of assigned rights/roles for books, chapters, pages needed for security (#1414)
Add testing to cover API response format.
Add testing to cover API config options.
Come up with a documentation strategy.

Thoughts

Versioning

API versioning seems sensible, and it's what you'd expect for a central public service, but I don't think it'd be best for this project. Versioning will essentially depend on BookStack internals, supporting version compatibility along with multiple versions will require a fair amount of effort while slowing change. I think it'd be best to have no version but just try to keep things stable where possible.

Documentation

Having some API docs will be important. Since they'd be tied & specific to BookStack versions, I'd prefer to keep the docs out of the main (bookstackapp.com) website and instead generate the docs to be included in the platform itself, so the docs would be accessible via your own BookStack instance.

Docs should be generated from controller and route code since I'd prefer us not to have multiple areas of comments/docs to update. Route & controller code and comments should be parsed to a flexible format that can be stored and later output in blade templates. Ideally it'd be nice to support swagger as an output option but I'd say we do that at a later point, focus on readable built-in docs for now.

Notes

Standard Error Response Format

{
	"error": {
		"code": 401,
		"message": "No authorization token found on the request"
	}
}

Standard Listing Response Format

{
	"data": [
		{
			"id": 1,
			"name": "BookStack User Guide",
			"slug": "bookstack-user-guide",
			"description": "This is a general guide on using BookStack on a day-to-day basis.",
			"created_at": "2019-05-05 21:48:46",
			"updated_at": "2019-12-11 20:57:31",
			"created_by": 1,
			"updated_by": 1,
			"restricted": 0,
			"image_id": 3
		}
	],
	"total": 14
}

List Operation Parameters

GET /api/books?count=2&offset=2&sort=-name&filter[name]=My+book&filter[id:gt]=5

$filterOperators = [
        'eq'   => '=',
        'ne'   => '!=',
        'gt'   => '>',
        'lt'   => '<',
        'gte'  => '>=',
        'lte'  => '<=',
        'like' => 'like'
    ]

_{🔄 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/1826 **Author:** [@ssddanbrown](https://github.com/ssddanbrown) **Created:** 12/28/2019 **Status:** ✅ Merged **Merged:** 1/18/2020 **Merged by:** [@ssddanbrown](https://github.com/ssddanbrown) **Base:** `master` ← **Head:** `api_origins` --- ### 📝 Commits (10+) - [`04137e7`](https://github.com/BookStackApp/BookStack/commit/04137e7c98cfe182f3c603e7d1acbc9a0ed524e7) Started core API route work - [`d336ba6`](https://github.com/BookStackApp/BookStack/commit/d336ba687460d2bca898e86c12a26224fc36f071) Started work on API token controls - [`dccb279`](https://github.com/BookStackApp/BookStack/commit/dccb279c84a3f523f1c07ffc4ee4e2b526fd5384) Built out interfaces & endpoints for API token managment - [`832fbd6`](https://github.com/BookStackApp/BookStack/commit/832fbd65afcaa8d8f2953fe04de2e479053dbc29) Added testing coverage to user API token interfaces - [`692fc46`](https://github.com/BookStackApp/BookStack/commit/692fc46c7dfab76f4e9e28a9f1b4c419f60b5ded) Removed token 'client' text, avoid confusion w/ oAuth - [`2cfa373`](https://github.com/BookStackApp/BookStack/commit/2cfa37399c6b7f5b743db8223dd90d3dba68d6fa) Fixed some empty-expiry conditions of token ui flows - [`3de55ee`](https://github.com/BookStackApp/BookStack/commit/3de55ee6454667e2d4b3cb866625a165ccb9aee3) Linked new API token system into middleware - [`349b462`](https://github.com/BookStackApp/BookStack/commit/349b4629bef25e4631c1024749726415507b2cd5) Extracted API auth into guard - [`6f1b88a`](https://github.com/BookStackApp/BookStack/commit/6f1b88a6a6402c7acfdd3e9bef72f50eb5e975c1) Change email confirmation from own middle to trait - [`3d11cba`](https://github.com/BookStackApp/BookStack/commit/3d11cba223cad16ad13faee010259e97b05dcee9) Added testing coverage to API token auth ### 📊 Changes **71 files changed** (+2556 additions, -99 deletions) <details> <summary>View changed files</summary> 📝 `.env.example.complete` (+6 -0) ➕ `app/Api/ApiDocsGenerator.php` (+125 -0) ➕ `app/Api/ApiToken.php` (+31 -0) ➕ `app/Api/ApiTokenGuard.php` (+166 -0) ➕ `app/Api/ListingResponseBuilder.php` (+135 -0) 📝 `app/Auth/Role.php` (+1 -1) 📝 `app/Auth/User.php` (+15 -6) 📝 `app/Auth/UserRepo.php` (+1 -0) ➕ `app/Config/api.php` (+23 -0) 📝 `app/Config/auth.php` (+1 -3) 📝 `app/Entities/Book.php` (+2 -1) ➕ `app/Exceptions/ApiAuthException.php` (+7 -0) 📝 `app/Exceptions/Handler.php` (+42 -0) ➕ `app/Exceptions/UnauthorizedException.php` (+17 -0) ➕ `app/Http/Controllers/Api/ApiController.php` (+30 -0) ➕ `app/Http/Controllers/Api/ApiDocsController.php` (+47 -0) ➕ `app/Http/Controllers/Api/BooksApiController.php` (+101 -0) ➕ `app/Http/Controllers/UserApiTokenController.php` (+139 -0) 📝 `app/Http/Controllers/UserController.php` (+8 -6) 📝 `app/Http/Kernel.php` (+4 -7) _...and 51 more files_ </details> ### 📄 Description Create some level of baseline API implementation. This will cover just the basic CRUD book endpoints and nothing more. The purpose of this is to get a basic implementation in place for feedback to ensure it's sensible before scaling it out to many other endpoints. ### TODO - [x] Implement #1414 - [x] Add testing to cover API response format. - [x] Add testing to cover API config options. - [x] Come up with a documentation strategy. ### Thoughts ##### Versioning API versioning seems sensible, and it's what you'd expect for a central public service, but I don't think it'd be best for this project. Versioning will essentially depend on BookStack internals, supporting version compatibility along with multiple versions will require a fair amount of effort while slowing change. I think it'd be best to have no version but just try to keep things stable where possible. ##### Documentation Having some API docs will be important. Since they'd be tied & specific to BookStack versions, I'd prefer to keep the docs out of the main (bookstackapp.com) website and instead generate the docs to be included in the platform itself, so the docs would be accessible via your own BookStack instance. Docs should be generated from controller and route code since I'd prefer us not to have multiple areas of comments/docs to update. Route & controller code and comments should be parsed to a flexible format that can be stored and later output in blade templates. Ideally it'd be nice to support swagger as an output option but I'd say we do that at a later point, focus on readable built-in docs for now. ### Notes ##### Standard Error Response Format ```json { "error": { "code": 401, "message": "No authorization token found on the request" } } ``` ##### Standard Listing Response Format ```json { "data": [ { "id": 1, "name": "BookStack User Guide", "slug": "bookstack-user-guide", "description": "This is a general guide on using BookStack on a day-to-day basis.", "created_at": "2019-05-05 21:48:46", "updated_at": "2019-12-11 20:57:31", "created_by": 1, "updated_by": 1, "restricted": 0, "image_id": 3 } ], "total": 14 } ``` ##### List Operation Parameters ```http GET /api/books?count=2&offset=2&sort=-name&filter[name]=My+book&filter[id:gt]=5 ``` ```php $filterOperators = [ 'eq' => '=', 'ne' => '!=', 'gt' => '>', 'lt' => '<', 'gte' => '>=', 'lte' => '<=', 'like' => 'like' ] ``` --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

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

OVERLORD closed this issue

2026-02-05 10:20:01 +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#5902