{"title":"CMS as a service","number":4,"body":{"flavor":"markdown","text":"No web site should be a silo. A CMS should be great at organizing,\nsyndicating, and presenting your content, but it should also\ncommunicate with arbitrary applications outside the CMS.\nIn particular, mobile applications should be able to use the data\nfrom the CMS.\nIn DecentCMS, you can enable the `content-api` feature to expose all\ncontent items as JSON documents.\n\nContent items are then available under two endpoints: `src` and\n`shapes`.\n\nThe first one, `src`, returns the source document for the content\nitem.\nIt is available under URLs of the form `/api/src/[id]`.\nFor example, you can get the source document for this topic by\nnavigating to\n[/api/src/docs:decent-core-content/cms-as-a-service](/api/src/docs:decent-core-content/cms-as-a-service).\nIt's possible to get to any item this way, such as the copyright\nwidget on the bottom of this page:\n[/api/src/widget:copyright](/api/src/widget:copyright).\n\nNote that the formatting of the document will be a compact view, or a\npretty printed, legible version depending on whether the site is\nrunning in release or debug mode.\n\nThe source view is useful, but doesn't always contain all the needed\ninformation.\nFor example, here is the document that you'd get from\n`/api/src/pages` for a query on all page content items, if such a\nsearch page is available under the id `/pages`:\n\n```json\n{\n \"meta\": {\n \"type\": \"search-page\"\n },\n \"title\": \"Pages\",\n \"query\": {\n \"indexName\": \"pages\",\n \"idFilter\": \"^[^:]+$\",\n \"map\": \"item.meta.type !== 'page' ? null : {title: item.title, url: item.id}\",\n \"orderBy\": \"entry.title\",\n \"pageSize\": 10\n },\n \"id\": \"pages\"\n}\n```\n\nThis is useful, if you're trying to edit the query, but not so much\nif you're trying to get its actual results.\nThis is where the second endpoint becomes useful.\n\nNavigating to the second endpoint for the same item,\n`/api/shapes/pages`, will give a document looking like this:\n\n```json\n{\n \"title\": {\n \"meta\": {\n \"type\": \"title\",\n \"name\": \"title\"\n },\n \"text\": \"Pages\"\n },\n \"query-results\": {\n \"indexName\": \"pages\",\n \"idFilter\": \"^[^:]+$\",\n \"map\": \"item.meta.type !== 'page' ? null : {title: item.title, url: item.id}\",\n \"orderBy\": \"entry.title\",\n \"pageSize\": 10,\n \"meta\": {\n \"type\": \"search-results\",\n \"name\": \"query-results\",\n \"alternates\": [\n \"search-results-query\",\n \"search-results-pages\",\n \"search-results-query-pages\"\n ]\n },\n \"results\": [\n {\n \"title\": \"Contact\",\n \"url\": \"/contact\",\n \"itemId\": \"/contact\",\n \"_order\": \"Contact\"\n },\n {\n \"title\": \"Your CMS Expert\",\n \"url\": \"/\",\n \"itemId\": \"/\",\n \"_order\": \"Your CMS Expert\"\n }\n ]\n }\n}\n```\n\nThis is the result of letting all shape handlers run on the content\nitem.\n\nIn this particular case, the title part handler, and the search part\nhandler each built a shape.\nThe search handler in particular ran the query and added its results\nto its own shape.\nThose results can be found under `['query-results'].results`.","html":"
No web site should be a silo. A CMS should be great at organizing,\nsyndicating, and presenting your content, but it should also\ncommunicate with arbitrary applications outside the CMS.\nIn particular, mobile applications should be able to use the data\nfrom the CMS.\nIn DecentCMS, you can enable the content-api
feature to expose all\ncontent items as JSON documents.
Content items are then available under two endpoints: src
and\nshapes
.
The first one, src
, returns the source document for the content\nitem.\nIt is available under URLs of the form /api/src/[id]
.\nFor example, you can get the source document for this topic by\nnavigating to\n/api/src/docs:decent-core-content/cms-as-a-service.\nIt's possible to get to any item this way, such as the copyright\nwidget on the bottom of this page:\n/api/src/widget:copyright.
Note that the formatting of the document will be a compact view, or a\npretty printed, legible version depending on whether the site is\nrunning in release or debug mode.
\nThe source view is useful, but doesn't always contain all the needed\ninformation.\nFor example, here is the document that you'd get from\n/api/src/pages
for a query on all page content items, if such a\nsearch page is available under the id /pages
:
{\n "meta": {\n "type": "search-page"\n },\n "title": "Pages",\n "query": {\n "indexName": "pages",\n "idFilter": "^[^:]+$",\n "map": "item.meta.type !== 'page' ? null : {title: item.title, url: item.id}",\n "orderBy": "entry.title",\n "pageSize": 10\n },\n "id": "pages"\n}
\nThis is useful, if you're trying to edit the query, but not so much\nif you're trying to get its actual results.\nThis is where the second endpoint becomes useful.
\nNavigating to the second endpoint for the same item,\n/api/shapes/pages
, will give a document looking like this:
{\n "title": {\n "meta": {\n "type": "title",\n "name": "title"\n },\n "text": "Pages"\n },\n "query-results": {\n "indexName": "pages",\n "idFilter": "^[^:]+$",\n "map": "item.meta.type !== 'page' ? null : {title: item.title, url: item.id}",\n "orderBy": "entry.title",\n "pageSize": 10,\n "meta": {\n "type": "search-results",\n "name": "query-results",\n "alternates": [\n "search-results-query",\n "search-results-pages",\n "search-results-query-pages"\n ]\n },\n "results": [\n {\n "title": "Contact",\n "url": "/contact",\n "itemId": "/contact",\n "_order": "Contact"\n },\n {\n "title": "Your CMS Expert",\n "url": "/",\n "itemId": "/",\n "_order": "Your CMS Expert"\n }\n ]\n }\n}
\nThis is the result of letting all shape handlers run on the content\nitem.
\nIn this particular case, the title part handler, and the search part\nhandler each built a shape.\nThe search handler in particular ran the query and added its results\nto its own shape.\nThose results can be found under ['query-results'].results
.