robinscholz / better-rest
Kirby Plugin for better REST requests
Installs: 502
Dependents: 0
Suggesters: 1
Security: 0
Stars: 51
Watchers: 1
Forks: 3
Open Issues: 8
Type:kirby-plugin
Requires
- php: >=7.3.0
- getkirby/composer-installer: ^1.1
Requires (Dev)
- getkirby/cms: ^3.2
- nunomaduro/phpinsights: ^1.8
- php-coveralls/php-coveralls: ^2.1
- phpunit/phpunit: ^8.3
This package is auto-updated.
Last update: 2024-10-19 23:29:00 UTC
README
A Kirby plugin that exposes the internal REST API at /rest
with the option to convert Kirbytags to HTML and add a srcset
to images in the process. Intended to convert Kirby into a headless CMS.
Disclaimer
While this plugin is still functional, quite a few alternatives exist for turning Kirby into a headless content management system. If you are looking for a more sophisticated and modern solution, please take a look at the Kirby Query Language plugin, the recent work of Johann Schopplich or Kirby Content Representations.
Usage
The API can be accessed at /rest
. The plugin only allows GET
requests.
Authentification
Requests need to be authenticated via Basic Auth. It’s recommended to create a seperate API User with either a custom blueprint or with the one provided by this plugin called better-rest API. Read more about user roles in the docs.
Basic Auth needs to be enabled in the site/config/config.php
:
return [
'api' => [
'basicAuth' => true
]
];
Kirby 3 API
Examples:
rest/pages/:id
: https://getkirby.com/docs/reference/api/pagesrest/site
: https://getkirby.com/docs/reference/api/siterest/users/:id
: https://getkirby.com/docs/reference/api/users
Better-Rest Settings from Query
All standard setting as well as settings defined in site/config/onfig.php
can be overwritten on a per-request basis. Simply prefix the setting with br-
and include it as a query.
Examples:
rest/pages/test?br-srcset=375,1200
: br-srcsetrest/pages/test?br-smartypants=1
: br-smartypantsrest/pages/test?br-language=fr
: br-languagerest/pages/test?br-kirbytags=0&br-srcset=0
: br-kirbytag br-srcset
Multilang
The plugin supports multiple language settings. To fetch content for a specific language include a X-Language header containing the desired language code with your request. Alternatively a br-language
query can be used.
Settings
Config File
- The plugin converts kirbytags to HTML and adds a
srcset
to images by default. - Additionally it is possible to enable smartypants.
- To overwrite the default language it is possible to set a language code.
All settings need to be prefixed with robinscholz.better-rest.
!
Caveats
HTTPS
The Kirby installation needs to be served with a TLS Certicificate via https
.
Local setup
For local development use Laravel Valet or disable https
in the site/config/config.php
:
return [ 'api' => [ 'basicAuth' => true, 'allowInsecure' => true ] ];
WARNING: Do not use this setting for production environments!
Installation
Download
Download and copy this repository to /site/plugins/better-rest
.
Composer
composer require robinscholz/better-rest
Git submodule
git submodule add https://github.com/robinscholz/better-rest.git site/plugins/better-rest
Credits
A big thanks to @bnomei who refactored the initial source code into something extendable and future proof. If you are using this plugin please consider buying him a ☕!
License
MIT