API Builder
This headless starter includes an Express-esque API builder, defined in the JohannSchopplich\Headless\Api\Api class. You can use it to reuse logic such as handling a token or validating some other incoming data.
Take a look at the built-in routes to get an idea of how you can use the API builder to chain complex route logic.
Examples
Extend Kirby's Routing
The following example demonstrates how to create a simple API route that returns a JSON response. It is accessible under /hello-world.
use JohannSchopplich\Headless\Api\Api;
use JohannSchopplich\Headless\Api\Middlewares;
return [
'routes' => [
[
'pattern' => 'hello-world',
'method' => 'GET',
'action' => Api::createHandler(
// Middleware to check if a bearer token is sent with the request
[Middlewares::class, 'hasBearerToken'],
// Handler function to execute if the middleware passes
function (array $context) {
// Access the `foo` query parameter
$foo = kirby()->request()->get('foo');
// Do something with `$foo` here
return Api::createResponse(200, [
'foo' => $foo
]);
}
)
]
]
];
Extend Kirby's API
If you want to create an API route that is accessible under /api/my-endpoint, you can use the api option in your config.php. This will add the endpoint to Kirby's API routes.
use JohannSchopplich\Headless\Api\Api;
use JohannSchopplich\Headless\Api\Middlewares;
return [
'api' => [
'routes' => [
[
'pattern' => 'my-endpoint',
// Accept only POST requests
'method' => 'POST',
// Disable authentication, since the middleware will check for a bearer token
'auth' => false,
'action' => Api::createHandler(
// Middleware to check if a bearer token is sent with the request
[Middlewares::class, 'hasBearerToken'],
// Handler function to execute if the middleware passes
function (array $context) {
$foo = kirby()->request()->get('foo');
// Do something with `$foo` here
return Api::createResponse(201, [
'foo' => $foo
]);
}
)
]
]
]
];
Middlewares
You can use one of the built-in middlewares or define your own custom middleware.
This example demonstrates how to create a custom middleware that checks if a date query parameter is sent with the request. If not, it will return a 401 error:
use JohannSchopplich\Headless\Api\Api;
$hasDateQuery = function (array $context) {
if (empty(kirby()->request()->get('date'))) {
return Api::createResponse(401);
}
};
Use the middleware in your route configuration like this:
use JohannSchopplich\Headless\Api\Api;
return [
'routes' => [
[
'pattern' => 'my-endpoint',
'method' => 'POST',
'action' => Api::createHandler(
$hasDateQuery,
function (array $context) {
$date = kirby()->request()->get('date');
return Api::createResponse(201, [
'date' => $date
]);
}
)
]
]
];