starred/BookStack
1
0
Fork 0
mirror of https://github.com/BookStackApp/BookStack.git synced 2026-02-07 11:19:38 +03:00
Code Issues 784 Packages Projects Releases 10 Wiki Activity

API Feedback #1499

New Issue
Closed
opened 2026-02-05 01:03:53 +03:00 by OVERLORD · 22 comments
OVERLORD commented 2026-02-05 01:03:53 +03:00
Owner
Copy Link

Originally created by @ssddanbrown on GitHub (Jan 19, 2020).

This issue has been created to capture any feedback regarding the base API implementation included in v0.28.

Please do not ask for new API endpoints as part of this feedback, this is about capturing feedback on the foundation elements (Authentication, Request & Response formats, Parameters, Documentation etc...).

Originally created by @ssddanbrown on GitHub (Jan 19, 2020). This issue has been created to capture any feedback regarding the base API implementation included in v0.28. _Please do not ask for new API endpoints as part of this feedback, this is about capturing feedback on the foundation elements (Authentication, Request & Response formats, Parameters, Documentation etc...)._
OVERLORD added the ☕ Open to discussion🏭 Back-End labels 2026-02-05 01:03:53 +03:00
OVERLORD commented 2026-02-05 01:03:58 +03:00
Author
Owner
Copy Link

@homotechsual commented on GitHub (Feb 18, 2020):

It looks good - it'd be nice to aim for an OpenAPI or Swagger compliant API implementation to make it possible to programmatically generate client implementations using SwaggerGen.

https://swagger.io/

Edit:

It'd also be very nice to have a command line API client shipped with bookstack for automation via Cron jobs.

@homotechsual commented on GitHub (Feb 18, 2020): It looks good - it'd be nice to aim for an OpenAPI or Swagger compliant API implementation to make it possible to programmatically generate client implementations using SwaggerGen. https://swagger.io/ **Edit:** It'd also be very nice to have a command line API client shipped with bookstack for automation via Cron jobs.
OVERLORD commented 2026-02-05 01:04:01 +03:00
Author
Owner
Copy Link

@grasshopper139 commented on GitHub (Feb 20, 2020):

I am having issues with authentication. I created a token, but I continue to get 401 errors stating that no token was found.

curl -k --request GET --url https://192.168.1.10/api/books --header 'Authorization: token <token_id>:<token_secret>'

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

@grasshopper139 commented on GitHub (Feb 20, 2020): I am having issues with authentication. I created a token, but I continue to get 401 errors stating that no token was found. curl -k --request GET --url https://192.168.1.10/api/books --header 'Authorization: token <token_id>:<token_secret>' {"error":{"code":401,"message":"No authorization token found on the request"}}
OVERLORD commented 2026-02-05 01:04:04 +03:00
Author
Owner
Copy Link

@ssddanbrown commented on GitHub (Feb 21, 2020):

@grasshopper139 Have you tried with a capital t on Token within the header value? Although I would expected that to lead to an "incorrect token value" error instead of "no token" error.

Additionally, do you have other stuff running in the middle? Like a reverse proxy?

@ssddanbrown commented on GitHub (Feb 21, 2020): @grasshopper139 Have you tried with a capital `t` on `Token` within the header value? Although I would expected that to lead to an "incorrect token value" error instead of "no token" error. Additionally, do you have other stuff running in the middle? Like a reverse proxy?
OVERLORD commented 2026-02-05 01:04:06 +03:00
Author
Owner
Copy Link

@ssddanbrown commented on GitHub (Feb 21, 2020):

@MikeyMJCO Thanks for the input. I did originally look to support Swagger/OpenAPI but I felt getting all the data required and working to the exact format was going to take too much time and ongoing effort, at least for now.

I have ensured I've exposed the internal BookStack docs structure, found at /api/docs.json so people can auto-convert that to auto-gen API-apps or attempt to morph the data to other formats if they wish.

In regards to a CLI, I'm happy to support maintenance or operational tasks via the command line as we do now, where it makes sense, but I don't think another full-fledged API interface would be worth maintaining especially since the REST API could be scripted against and cron'd.

@ssddanbrown commented on GitHub (Feb 21, 2020): @MikeyMJCO Thanks for the input. I did originally look to support Swagger/OpenAPI but I felt getting all the data required and working to the exact format was going to take too much time and ongoing effort, at least for now. I have ensured I've exposed the internal BookStack docs structure, found at `/api/docs.json` so people can auto-convert that to auto-gen API-apps or attempt to morph the data to other formats if they wish. In regards to a CLI, I'm happy to support maintenance or operational tasks via the command line as we do now, where it makes sense, but I don't think another full-fledged API interface would be worth maintaining especially since the REST API could be scripted against and cron'd.
OVERLORD commented 2026-02-05 01:04:07 +03:00
Author
Owner
Copy Link

@grasshopper139 commented on GitHub (Feb 21, 2020):

@ssddanbrown I have tried with both Upper and Lower case 'T'. I receive the same error in both cases. I have nothing else running in the middle.

.htaccess:

<IfModule mod_rewrite.c>
    <IfModule mod_negotiation.c>
        Options -MultiViews -Indexes
    </IfModule>

    RewriteEngine On

    # Redirect Trailing Slashes If Not A Folder...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)/$ /$1 [L,R=301]

    # Handle Front Controller...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</IfModule>

.env:

# Enable DeBugging
# Error log can be found at the path storage/logs/laravel.log
APP_DEBUG=true

# Application key
# Used for encryption where needed.
# Run `php artisan key:generate` to generate a valid key.
APP_KEY=<app_key>

# Application URL
# Remove the hash below and set a URL if using BookStack behind
# a proxy, if using a third-party authentication option.
# This must be the root URL that you want to host BookStack on.
# All URL's in BookStack will be generated using this value.
#APP_URL=https://example.com

# Database details
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=<db_username>
DB_PASSWORD=<db_password>

# Mail system to use
# Can be 'smtp', 'mail' or 'sendmail'
MAIL_DRIVER=smtp

# SMTP mail options
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

#
# LDAP Configurations
#
# General auth
AUTH_METHOD=ldap

# The LDAP host, Adding a port is optional
#LDAP_SERVER=example.com:389
# If using LDAP over SSL you should also define the protocol:
LDAP_SERVER=ldaps://<ldap_ip>

# The base DN from where users will be searched within
LDAP_BASE_DN=<base_people_ou>

# The full DN and password of the user used to search the server
# Can both be left as false to bind anonymously
LDAP_DN=<ldap_dn>
LDAP_PASS=<ldap_password>

# A filter to use when searching for users
# The user-provided user-name used to replace any occurrences of '${user}'
LDAP_USER_FILTER=(&(uid=${user}))

# Set the LDAP version to use when connecting to the server
LDAP_VERSION=3

# Set the default 'email' attribute. Defaults to 'mail'
LDAP_EMAIL_ATTRIBUTE=mail

# Set the property to use for a user's display name. Defaults to 'cn'
LDAP_DISPLAY_NAME_ATTRIBUTE=cn

# If you need to allow untrusted LDAPS certificates, add the below and uncomment (remove the #)
# Only set this option if debugging or you're absolutely sure it's required for your setup.
LDAP_TLS_INSECURE=true

# Enable LDAP group sync, Set to 'true' to enable.
#LDAP_USER_TO_GROUPS=true

# LDAP user attribute containing groups, Defaults to 'memberOf'.
#LDAP_GROUP_ATTRIBUTE="gidNumber"

# Remove users from roles that don't match LDAP groups.
LDAP_REMOVE_FROM_GROUPS=false
# A full list of options can be found in the '.env.example.complete' file.

httpd.conf:

DocumentRoot "/var/www/BookStack/public"

<Directory /var/www/BookStack/public>
    Require all granted
    AllowOverride All
    Options +FollowSymlinks

    RewriteEngine On

    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</Directory>

<IfModule dir_module>
    DirectoryIndex index.html
</IfModule>

<Files ".ht*">
    Require all denied
</Files>

<Directory "/var/www/cgi-bin">
    AllowOverride None
    Options None
    Require all granted
</Directory>
@grasshopper139 commented on GitHub (Feb 21, 2020): @ssddanbrown I have tried with both Upper and Lower case 'T'. I receive the same error in both cases. I have nothing else running in the middle. .htaccess: ``` <IfModule mod_rewrite.c> <IfModule mod_negotiation.c> Options -MultiViews -Indexes </IfModule> RewriteEngine On # Redirect Trailing Slashes If Not A Folder... RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^(.*)/$ /$1 [L,R=301] # Handle Front Controller... RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^ index.php [L] </IfModule> ``` .env: ``` # Enable DeBugging # Error log can be found at the path storage/logs/laravel.log APP_DEBUG=true # Application key # Used for encryption where needed. # Run `php artisan key:generate` to generate a valid key. APP_KEY=<app_key> # Application URL # Remove the hash below and set a URL if using BookStack behind # a proxy, if using a third-party authentication option. # This must be the root URL that you want to host BookStack on. # All URL's in BookStack will be generated using this value. #APP_URL=https://example.com # Database details DB_HOST=localhost DB_DATABASE=bookstack DB_USERNAME=<db_username> DB_PASSWORD=<db_password> # Mail system to use # Can be 'smtp', 'mail' or 'sendmail' MAIL_DRIVER=smtp # SMTP mail options MAIL_HOST=localhost MAIL_PORT=1025 MAIL_USERNAME=null MAIL_PASSWORD=null MAIL_ENCRYPTION=null # # LDAP Configurations # # General auth AUTH_METHOD=ldap # The LDAP host, Adding a port is optional #LDAP_SERVER=example.com:389 # If using LDAP over SSL you should also define the protocol: LDAP_SERVER=ldaps://<ldap_ip> # The base DN from where users will be searched within LDAP_BASE_DN=<base_people_ou> # The full DN and password of the user used to search the server # Can both be left as false to bind anonymously LDAP_DN=<ldap_dn> LDAP_PASS=<ldap_password> # A filter to use when searching for users # The user-provided user-name used to replace any occurrences of '${user}' LDAP_USER_FILTER=(&(uid=${user})) # Set the LDAP version to use when connecting to the server LDAP_VERSION=3 # Set the default 'email' attribute. Defaults to 'mail' LDAP_EMAIL_ATTRIBUTE=mail # Set the property to use for a user's display name. Defaults to 'cn' LDAP_DISPLAY_NAME_ATTRIBUTE=cn # If you need to allow untrusted LDAPS certificates, add the below and uncomment (remove the #) # Only set this option if debugging or you're absolutely sure it's required for your setup. LDAP_TLS_INSECURE=true # Enable LDAP group sync, Set to 'true' to enable. #LDAP_USER_TO_GROUPS=true # LDAP user attribute containing groups, Defaults to 'memberOf'. #LDAP_GROUP_ATTRIBUTE="gidNumber" # Remove users from roles that don't match LDAP groups. LDAP_REMOVE_FROM_GROUPS=false # A full list of options can be found in the '.env.example.complete' file. ``` httpd.conf: ``` DocumentRoot "/var/www/BookStack/public" <Directory /var/www/BookStack/public> Require all granted AllowOverride All Options +FollowSymlinks RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^ index.php [L] </Directory> <IfModule dir_module> DirectoryIndex index.html </IfModule> <Files ".ht*"> Require all denied </Files> <Directory "/var/www/cgi-bin"> AllowOverride None Options None Require all granted </Directory> ```
OVERLORD commented 2026-02-05 01:04:13 +03:00
Author
Owner
Copy Link

@homotechsual commented on GitHub (Feb 21, 2020):

@grasshopper139 try double quoting the token in Curl. It treats ":" as a special delimiter.

So try: curl -k --request GET --url https://192.168.1.10/api/books --header "Authorization: token <token_id>:<token_secret>"

@homotechsual commented on GitHub (Feb 21, 2020): @grasshopper139 try double quoting the token in Curl. It treats ":" as a special delimiter. So try: `curl -k --request GET --url https://192.168.1.10/api/books --header "Authorization: token <token_id>:<token_secret>"`
OVERLORD commented 2026-02-05 01:04:18 +03:00
Author
Owner
Copy Link

@grasshopper139 commented on GitHub (Feb 21, 2020):

@MikeyMJCO I get the same error. I even tried escaping the ':'.

@grasshopper139 commented on GitHub (Feb 21, 2020): @MikeyMJCO I get the same error. I even tried escaping the ':'.
OVERLORD commented 2026-02-05 01:04:21 +03:00
Author
Owner
Copy Link

@homotechsual commented on GitHub (Feb 21, 2020):

Just tested on my end and the curl command works perfectly - we're running on Nginx though.

@homotechsual commented on GitHub (Feb 21, 2020): Just tested on my end and the curl command works perfectly - we're running on Nginx though.
OVERLORD commented 2026-02-05 01:04:26 +03:00
Author
Owner
Copy Link

@grasshopper139 commented on GitHub (Feb 21, 2020):

I found the solution. In case anyone else runs into this issue using Apache on CentOS.

It seems that Apache was stripping the Authorization header. Adding this line to httpd.conf resolved the issue.

SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
@grasshopper139 commented on GitHub (Feb 21, 2020): I found the solution. In case anyone else runs into this issue using Apache on CentOS. It seems that Apache was stripping the Authorization header. Adding this line to httpd.conf resolved the issue. ``` SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 ```
OVERLORD commented 2026-02-05 01:04:28 +03:00
Author
Owner
Copy Link

@lithium-ap commented on GitHub (Feb 23, 2020):

I am having issues with authentication. I created a token, but I continue to get 401 errors stating that no token was found.

curl -k --request GET --url https://192.168.1.10/api/books --header 'Authorization: token <token_id>:<token_secret>'

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

I'm having the same issue, tried suggested fixes here, no luck. Running apache on ubuntu 16.04

@lithium-ap commented on GitHub (Feb 23, 2020): > I am having issues with authentication. I created a token, but I continue to get 401 errors stating that no token was found. > > curl -k --request GET --url https://192.168.1.10/api/books --header 'Authorization: token <token_id>:<token_secret>' > > {"error":{"code":401,"message":"No authorization token found on the request"}} I'm having the same issue, tried suggested fixes here, no luck. Running apache on ubuntu 16.04
OVERLORD commented 2026-02-05 01:04:32 +03:00
Author
Owner
Copy Link

@osmansorkar commented on GitHub (Feb 23, 2020):

I am having issues with authentication. I created a token, but I continue to get 401 errors stating that no token was found.
curl -k --request GET --url https://192.168.1.10/api/books --header 'Authorization: token <token_id>:<token_secret>'
{"error":{"code":401,"message":"No authorization token found on the request"}}

I'm having the same issue, tried suggested fixes here, no luck. Running apache on ubuntu 16.04

@lithium-ap you may try by add this commit lines on your .htaccess file .

RewriteCond %{HTTP:Authorization} .
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
@osmansorkar commented on GitHub (Feb 23, 2020): > > > > I am having issues with authentication. I created a token, but I continue to get 401 errors stating that no token was found. > > curl -k --request GET --url https://192.168.1.10/api/books --header 'Authorization: token <token_id>:<token_secret>' > > {"error":{"code":401,"message":"No authorization token found on the request"}} > > I'm having the same issue, tried suggested fixes here, no luck. Running apache on ubuntu 16.04 @lithium-ap you may try by add [this ](https://github.com/BookStackApp/BookStack/pull/1908/commits/01adf39be8fdaed911712170ded91ae878dfa254) commit lines on your .htaccess file . RewriteCond %{HTTP:Authorization} . RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
OVERLORD commented 2026-02-05 01:04:36 +03:00
Author
Owner
Copy Link

@lithium-ap commented on GitHub (Feb 23, 2020):

@lithium-ap you may try by add this commit lines on your .htaccess file .

RewriteCond %{HTTP:Authorization} .
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

Yes, this worked. Thank you!

@lithium-ap commented on GitHub (Feb 23, 2020): > @lithium-ap you may try by add [this ](https://github.com/BookStackApp/BookStack/pull/1908/commits/01adf39be8fdaed911712170ded91ae878dfa254) commit lines on your .htaccess file . > > ``` > RewriteCond %{HTTP:Authorization} . > RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}] > ``` Yes, this worked. Thank you!
OVERLORD commented 2026-02-05 01:04:38 +03:00
Author
Owner
Copy Link

@lithium-ap commented on GitHub (Feb 24, 2020):

Not sure if this is off topic, or violates the spirit of this issue. Are we able to POST a doc? I'm not seeing in documentation.

@lithium-ap commented on GitHub (Feb 24, 2020): Not sure if this is off topic, or violates the spirit of this issue. Are we able to POST a doc? I'm not seeing in documentation.
OVERLORD commented 2026-02-05 01:04:40 +03:00
Author
Owner
Copy Link

@ssddanbrown commented on GitHub (Feb 24, 2020):

@lithium-ap Only Book endpoints are supported right now. Wanted to ensure the base stuff (Auth, docs, API format) was good before expanding it out.

@ssddanbrown commented on GitHub (Feb 24, 2020): @lithium-ap Only `Book` endpoints are supported right now. Wanted to ensure the base stuff (Auth, docs, API format) was good before expanding it out.
OVERLORD commented 2026-02-05 01:04:41 +03:00
Author
Owner
Copy Link

@lithium-ap commented on GitHub (Feb 24, 2020):

@lithium-ap Only Book endpoints are supported right now. Wanted to ensure the base stuff (Auth, docs, API format) was good before expanding it out.

Thanks. I had no issues other than the header authorization that was fixed by adding the information to the .htacess. Looking forward to syncing information from passportal to bookstack!

@lithium-ap commented on GitHub (Feb 24, 2020): > @lithium-ap Only `Book` endpoints are supported right now. Wanted to ensure the base stuff (Auth, docs, API format) was good before expanding it out. Thanks. I had no issues other than the header authorization that was fixed by adding the information to the .htacess. Looking forward to syncing information from passportal to bookstack!
OVERLORD commented 2026-02-05 01:04:42 +03:00
Author
Owner
Copy Link

@MatthieuParis commented on GitHub (Mar 28, 2020):

Tested on Debian10 + Nginx and it works flawlessly. Thanks for the good work. This looks very promising.

@MatthieuParis commented on GitHub (Mar 28, 2020): Tested on Debian10 + Nginx and it works flawlessly. Thanks for the good work. This looks very promising.
OVERLORD commented 2026-02-05 01:04:45 +03:00
Author
Owner
Copy Link

@dvdl16 commented on GitHub (Apr 5, 2020):

Working great on Ubuntu 18.04 and Apache, thanks so much. I'm looking forward to more endpoints (e.g. adding new chapters and pages to books)

@dvdl16 commented on GitHub (Apr 5, 2020): Working great on Ubuntu 18.04 and Apache, thanks so much. I'm looking forward to more endpoints (e.g. adding new chapters and pages to books)
OVERLORD commented 2026-02-05 01:04:48 +03:00
Author
Owner
Copy Link

@kritschy commented on GitHub (May 12, 2020):

hi, thanks for the running api :) Is it possible to create books via the api directly within a shelf?

@kritschy commented on GitHub (May 12, 2020): hi, thanks for the running api :) Is it possible to create books via the api directly within a shelf?
OVERLORD commented 2026-02-05 01:04:49 +03:00
Author
Owner
Copy Link

@ssddanbrown commented on GitHub (May 12, 2020):

Hi @TheVeggie, Not at the moment, you'd have to do at least two operations (Create book then update shelf). Might also have to fetch the shelf first unless you already know the books on it.

@ssddanbrown commented on GitHub (May 12, 2020): Hi @TheVeggie, Not at the moment, you'd have to do at least two operations (Create book then update shelf). Might also have to fetch the shelf first unless you already know the books on it.
OVERLORD commented 2026-02-05 01:04:50 +03:00
Author
Owner
Copy Link

@kritschy commented on GitHub (May 14, 2020):

thank you :) @ssddanbrown

@kritschy commented on GitHub (May 14, 2020): thank you :) @ssddanbrown
OVERLORD commented 2026-02-05 01:04:52 +03:00
Author
Owner
Copy Link

@KeithIMyers commented on GitHub (Jul 7, 2020):

Good Morning,
It would be nice to have a API option that allows me to append to a existing book. I would love to create a book that can act as a log for some of the projects I am working on.

@KeithIMyers commented on GitHub (Jul 7, 2020): Good Morning, It would be nice to have a API option that allows me to append to a existing book. I would love to create a book that can act as a log for some of the projects I am working on.
OVERLORD commented 2026-02-05 01:04:57 +03:00
Author
Owner
Copy Link

@ssddanbrown commented on GitHub (Jan 9, 2021):

Thanks everyone for your feedback. As of v0.31 we now have core CRUD actions for shelves, books, chapters and pages: https://www.bookstackapp.com/blog/beta-release-v0-31-0/#api-update---pages

Additionally, I have setup a repo to house some API script examples that can be used as a base or for reference:
https://github.com/BookStackApp/api-scripts

Therefore I'm going to close this off but feel free to open new issues if you have a legitimate need for additional specific endpoints or features.

@ssddanbrown commented on GitHub (Jan 9, 2021): Thanks everyone for your feedback. As of v0.31 we now have core CRUD actions for shelves, books, chapters and pages: https://www.bookstackapp.com/blog/beta-release-v0-31-0/#api-update---pages Additionally, I have setup a repo to house some API script examples that can be used as a base or for reference: https://github.com/BookStackApp/api-scripts Therefore I'm going to close this off but feel free to open new issues if you have a legitimate need for additional specific endpoints or features.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
🎨 Design
📖 Docs Update
🐛 Bug
🐛 Bug
:cat2:🐈 Possible duplicate
💿 Database
☕ Open to discussion
💻 Front-End
🐕 Support
🚪 Authentication
🌍 Translations
🔌 API Task
🏭 Back-End
⛲ Upstream
🔨 Feature Request
🛠️ Enhancement
🛠️ Enhancement
🛠️ Enhancement
❤️ Happy feedback
🔒 Security
🔍 Pending Validation
💆 UX
📝 WYSIWYG Editor
🌔 Out of scope
🔩 API Request
:octocat: Admin/Meta
🖌️ View Customization
❓ Question
🚀 Priority
🛡️ Blocked
🚚 Export System
♿ A11y
🔧 Maintenance
> Markdown Editor
pull-request
Mirrored from GitHub Pull Request
No Label ☕ Open to discussion 🏭 Back-End
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
OVERLORD
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/BookStack#1499
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?