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/pages
rest/site : https://getkirby.com/docs/reference/api/site
rest/users/:id : https://getkirby.com/docs/reference/api/users

Official Kirby 3 API docs

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-srcset
rest/pages/test?br-smartypants=1 : br-smartypants
rest/pages/test?br-language=fr : br-language
rest/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.!

Settings	Default	Options
kirbytags	`true`	`boolean`
smartypants	`false`	`boolean`
srcset	`[375, 667, 1024, 1680]`	`Array` or `false`
language	`null`	`null` or `string`

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

robinscholz / better-rest

Maintainers

Details