I want to start a general discussion about the promise using Kirby decoupled/headless for front-end applications consuming its data.
So, I’m pretty new to Kirby. I evaluated tons of CMS for my clients and this year I found Kirby (with a couple of other solutions) being the way to go for my next projects.
Kirby keeps “promising” and mentioning that it’s also optimized for usage in a headless context and e.g. could be consumed by front-ends using whatever framework.
I’ve set myself up with a small Eleventy (11ty) test use case and this seems to work so far without issues. And thanks to the “Better Rest” plugin, I can also deal with KirbyText, which otherwise would be more difficult due to the fact, Kirby doesn’t simply use Markdown for all text formattings.
Which brings me to the point where I asked myself what the general idea is or was for developers to consume the API. Unless Kirby would provide an official SDK or library for the front-end that can deal with stuff like KirbyText, there is not much of a use case, from my point of view, why the API would respond with unparsed KirbyText. With other CMS and headless solutions either responding with HTML or markdown which at least is a no brainer to integrate into a decoupled web platform (and most likely also into other platforms like Android and iOS as it’s a widely adopted standard), it doesn’t make that much sense with KirbyText as it is it’s very own, Kirby specific thing.
The “Better Rest” plugins solves that problem and I even asked to also add markdown parsing in the plugin itself as it doesn’t make much sense to do one thing on the back-end and one thing on the front-end. But in general I believe, the cases from the “Better Rest” API plugin, including the KirbyText parsing and markdown parsing should come from the Kirby core, either per default, as a config or as a query parameter to define the format of the response.
In my opinion, this would make Kirby a real out of the box solution for headless/decoupled usage (maybe along with an API token functionality, but this is a whole other topic), without the need to rely on a third-party plugin.
My goal is to leverage this CMS (like all CMS) completely decoupled.
Opinions?
I’m not 100% sure what you really ask for; but this might be interesting for you to look at: https://github.com/getkirby/kql
Thanks for the reference. That looks interesting but I’m not sure it answers my request.
What I’m basically ask for is whether it wouldn’t make sense that the core API already handles KirbyText to HTML and Markdown to HTML conversion, either via configuration or URL parameter, without additional plugins. As, as long as the API responds with raw KirbyText content and Kirby not providing a client library to parse it, I don’t yet see the use case for the official, raw API (without plugins like Better Rest).
kql seems interesting, but yet the README is cryptic to me. Does it automatically respond with HTML content? As I see response examples containing HTML.
Hi, this is how I see it: the “core API” is built for the panel to interact with the php backend and mainly to work with the raw data I’ld assume.
If you want to go beyond that, you have to use kql, which enables you to write your own api endpoints and massage the data to your wishes. Of course, you could even setup your own API via a plugin too if you’ld want, where you can return everything you want, the way you want.
I also don’t get why you should port all core PHP functionality (e.g. kirbytext) to JS. This would only lead to more code, more potential bugs or changes in output which nobody would like?
I also don’t get why you should port all core PHP functionality (e.g. kirbytext) to JS. This would only lead to more code, more potential bugs or changes in output which nobody would like?
Okay, maybe it’s still unclear, so I try to clarify that point. It’s not about porting. It’s about consuming the data without porting, which the current API wouldn’t allow, thus which destroys the promise of the CMS that can be used headless (out of the box). That’s why my impression is there should be a built-in way to retrieve HTML and not KirbyText, to NOT make me have to port a KirbyText parsing functionality to JavaScript or Node or whatever platform consumes it.
As an example, other CMS made for headless consumption that might have a rather complex API with many individual features (e.g. Contenful), provide a client-side SDK to work with the data. That’s one solution to make it easier for the front-end developer, or for the case of Kirby, the better solution to not go there is bridging the KirbyText gap by allowing the retrieval of HTML. Without that, I have to port KirbyText parsing to the consumer platform, which you pointed out correctly, is a rather unstable story.
Now I think kql seems to be what I’m asking for as the examples all show HTML output, so I will check and test that. But my point stands: I believe this should be a core functionality to make this CMS fulfil the promise, quoting, “the perfect companion for your SPAs or mobile applications”. It might be with kql, but without it, sadly it isn’t.
Another option would be to have custom endpoints via JSON content representations that return exactly the data in the format you need.
@texnixe That’s clever solution I have to admit and I guess it would be worth adding a cross-reference between the API documentation and the content representations’ documentation as I would never have looked for an API solution under “templates” (in fact, templates is not interesting at all for me in the decoupled/headless case).
One drawback of course is the that it requires redundant work to define all the content representations I want to request from the API.
At this point I also tested kql, and I think that’s the way to go and I believe Kirby would really benefit from something like kql being in the core and part of the documentation.
That’s true, but it saves the trouble with authentication that is needed for the API because it currently doesn’t have a read-only mode.
Definitely.
Alright, you got an excellent point here. I didn’t think of that.