Bookstack: API Feedback

[ssddanbrown]

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...)._

[MikeyMJCO]

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.

[grasshopper139]

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 :'

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

[ssddanbrown]

@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]

@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.

[grasshopper139]

@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>

[MikeyMJCO]

@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>"

[grasshopper139]

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

[MikeyMJCO]

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

[grasshopper139]

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

[lithium-ap]

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 :'

{"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

[osmansorkar]

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 :'
{"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}]

[lithium-ap]

@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]

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.

[ssddanbrown]

@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.

[lithium-ap]

@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!

[MatthieuParis]

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

[dvdl16]

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)

[kritschy]

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

[ssddanbrown]

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.

[kritschy]

thank you :) @ssddanbrown

[KeithIMyers]

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.