REST API / Content representation


Could someone please explain to me the difference between REST API and Content Representation and in which use case we should use one or the other?

I read the documentation and this is what I’ve understood for the moment:


  • Output data in JSON from endpoints
  • Need authentication for security reason
  • REST API is used to read, update, delete data

Content Representation

  • Output data in JSON from representation template
  • Don’t need authentication, data is publicly available through an URL
  • Content Representation is only used to read data (no update/delete data possible)

Did I understand correctly?

What about the use case?

If I need to just read data or let anybody read data > I should use Content representation
If I need to let authorized user to read AND update/delete data, I should use the REST API …

yes i think so.

the rest api can take queries and return data in kirbys context (lots of data) and from your custom api endpoints (you custom data).

your custom content representations are as far as json goes just a simple way to dump an array. its limited to whatever you make it return.

Content representations can output any type of data. A .json representation would return JSON data, but you are not limited to JSON representations. Your representations can return an RSS feed or whatever type of data you want it to return.

Typical use cases for JSON content representations are Ajax requests.

For instance, if I want to sourcing data from Kirby (use Kirby as a headless CMS) to output these data in a static generator to build a static website, what do you think is best ? REST API or Content Representation and could you tell me why?

For use as a headless CMS, the REST API would be the right solution, because hat’s actually what the REST API is intended for. You might want to look into the Better REST plugin.

Better Rest is a sort of boilerplate to help us using the Kirby API?

Quoting @bnomei

to all lovers of headless cms. @robinscholz and i joined forces and extended his better-rest plugin.
it makes the kirby 3 api availabe at /rest (readonly, auth required), has build in support for kirbytags, smartypants, multilanguage setups and srcset. even if the readme does not reflect this yet (stupid caches) i added unittests with build:passing and coverage:100 to make sure future updates won’t break your frontend.

Thanks, it’s still a bit confused in my head when use the REST API or the Representation, but I probably need to use them in a concrete project to understand.

The REST API is already there for you to use. Why would you want to reinvent the wheel with content representations for the purpose of creating a static site?

Because the static generator Eleventy which I would like to use can consume .json files as input data.

Representation provides .json files, REST API provides JSON object through a js file (if I understood correctly).