Page API (Layout as a Service)

Last Updated: Jun 16, 2022
documentation for the dotCMS Content Management System

The PageAPI enables you to retrieve all the elements of any Page in your dotCMS system. The elements may be retrieved in JSON format, or as fully rendered HTML; regardless of the format chosen, each element is returned separately within it's own JSON object, making it easy to retrieve and use all page elements with a single call.

Elements returned by the Page API include:

  • Page information including URL and SEO
  • Body Layout information as rows/columns
  • Template/Theme information
  • All Content Blocks, including what content types they can take
  • Visitor Context Information (if a client side call)
  • Rendered versions of the page and all content blocks (optional)

To see a simple example of the Page API's render mode in action, you can try a live variation of the Javascript single-page app featured in the example section:

Try Page API Rendering

Note: For additional information on the usage and benefits of the Page REST API and Layout-as-a-Service, please see the Layout as a Service (LaaS) post in the dotCMS blog.

Usage

Calls to the Page API take the following form:

https://{server_address}/api/v1/page/{format}/{page_path}

Where:

  • {server_address} is replaced with the address of your dotCMS server.
  • {format} specifies the format to return each page element in.
    • Acceptable values are json or render.
  • {page_path} is replaced with the path to the page

Below is an example URL returns the page response from a page on the demo site. You must be logged in to see the response (email:admin@dotcms.com password:admin).

Parameters

The Page API accepts the following URL parameters:

  • mode — (LIVE | WORKING) if you want live or drafted content
  • host_id — the ID of the site the page is on (if different from the one in the URL)
  • language_id — the ID of the language variant you want to retrieve
  • com.dotmarketing.persona.id — the ID of the persona variant you want to retrieve
  • fireRules — (true | false) if you want to fire the rules set on the page

Examples

JSON Formatted Elements

The following call returns all the page elements of the dotCMS Demo site home page, with each page element being returned in JSON format:

(Remember: You must be logged into the Demo Site back end for this call to work.)

This call returns results which include all elements used to display the page, including the site, page, template, containers, content, and more. The following is a small sample of the information returned:

{
...
  "site" : {
    "lowIndexPriority" : false,
    "indexPolicyDependencies" : "DEFER",
    "default" : true,
    "aliases" : "localhost\n127.0.0.1",
    "inode" : "59bb8831-6706-4589-9ca0-ff74016e02b2",
    "hostname" : "demo.dotcms.com",
...
    "identifier" : "48190c8c-42c4-46af-8d1a-0cd5db894797",
    "modDate" : 1634235141702,
    "type" : "contentlet",
...
    "folder" : "SYSTEM_FOLDER",
    "archived" : false,
    "languageId" : 1,
    "working" : true,
    "modUser" : "dotcms.org.1",
...
  },
  "template" : {
    "iDate" : 1609946283995,
    "type" : "template",
    "owner" : "dotcms.org.1",
    "inode" : "1b90c278-0dfc-4ecc-ac5b-1827522ae469",
    "identifier" : "c6f813ef-f1f9-4759-a102-655bf441ec8e",
    "source" : "DB",
    "title" : "anonymous_layout_1609946283966",
    "friendlyName" : "",
    "modDate" : 1609946283996,
    "modUser" : "dotcms.org.1",
...

Fully Rendered Elements

The following call returns all the page elements of the dotCMS Demo Site home page, with each page element returned as fully rendered HTML, encapsulated within a JSON obect:

(Remember: You must be logged into the Demo Site back end for this call to work.)

This call returns all of the same elements as the previous call, but returns displayable elements as fully rendered HTML. For an example, click the link above, and view the source of the rendered HTML page.

JavaScript Application Example

The following HTML code includes a full Javascript application which uses the Page REST API to pull and display the fully rendered contents of the dotCMS Demo Site index page. The app draws a page's slug from the url hash, fetches its content, and then resituates it into a simple template.

You can also try out a live variation on the page below, which has been extended to include dynamic, user-specified Page API calls.

<html>
    <head>
        <script>
            function getUrl(){
                var url = (window.location.hash.length==0)
                    ? "/index" //// PATH/SLUG GOES HERE
                    : window.location.hash.substr(1);
                if(!url.startsWith("/")){
                    url = "/" + url;
                }
                if(url.endsWith("/")){
                    url = url + "index";
                }
                window.location.hash = url;
                // HERE IS THE API ENDPOINT TO GET THE LAYOUT as a SERVICE back, 
                // e.g. https://demo.dotcms.com/api/v1/page/render/index
                return "https://demo.dotcms.com/api/v1/page/render" + url;
            }
            var url = getUrl();
            console.log("reading:"+url);

            function readJson(url, callback) {
                var req = new XMLHttpRequest();
                req.open("GET", url, true);
                req.setRequestHeader("Authorization", "Basic " + btoa("admin@dotcms.com:admin")); 
                req.onreadystatechange = function() {
                    if (req.readyState === 4 && req.status == "200") {
                        callback(req.responseText);
                    }
                }
                req.send();
            }

            window.onload = 
                readJson(url, function(text){
                    var data = JSON.parse(text).entity;
                    if(window.location.search.indexOf("raw=")>-1){
                        document.body.innerHTML=text;
                    }
                    else if(data.layout){
                        writeLayoutDocument(data);
                    }
                    else{
                        writeRawDocument(data);
                    }
                });

            function writeRawDocument(data){    
                document.body.innerHTML=data.page.map.rendered;
            }

            function writeLayoutDocument(data){ 
                var rows = data.layout.body.rows;
                var myPage = document.createElement('div');
                document.body.appendChild(myPage);
                myPage.style.cssText = 'border:2px solid #9AB3CE;margin:10px;padding:10px;background:#E0E9F6';
                myPage.innerHTML="reading from : <a href='" + url + "'>" + url + "</a>";

                if(data.layout.header){
                    var header = document.createElement('div');
                    header.innerHTML="<h1>Including Header</h1>";
                    header.style.cssText = 'border:2px solid #9AB3CE;margin:10px;padding:10px;background:#E0E9F6';
                    document.body.appendChild(header);
                }

                for(i=0;i<rows.length;i++){
                    var row = rows[i];
                    var columns = row.columns;
                    var thisRow = document.createElement('div');
                    thisRow.style.cssText = 'display:flex;flex-direction:row;justify-content:space-between';
                    document.body.appendChild(thisRow);

                    for(j=0;j<columns.length;j++){
                        var column = columns[j];
                        var containers = column.containers;
                        var thisColumn = document.createElement('div');
                        thisColumn.style.cssText = 'flex-basis:' + (column.widthPercent-0) + '%;border:2px solid #9AB3CE;margin:10px;padding:10px;background:#EEF5F9';
                        thisRow.appendChild(thisColumn);

                        for(k=0;k<containers.length;k++){
                            var containerId = containers[k].identifier;
                            var containerUUID = containers[k].uuid;

                            var thisContainerInfo = document.createElement('div');
                            thisContainerInfo.style.cssText = "color:gray;text-align:right;"
                            thisColumn.appendChild(thisContainerInfo);
                            thisContainerInfo.innerHTML="{row:" + (i+1) + ",column:" + (j+1)+ ",width:" + column.widthPercent + "%}";
                            var thisContainer = document.createElement('div');
                            thisContainer.style.cssText = 'border:3px solid #9AB3CE;background:#ffffff;margin:10px;padding:10px;';
                            thisColumn.appendChild(thisContainer);

                            // add in the pre-rendered container content
                            console.log("rendered", containerUUID)
                            thisContainer.innerHTML=data.containers[ containerId ].rendered["uuid-" + containerUUID ];
                        }
                    }
                }
                if(data.layout.footer){
                    var footer = document.createElement('div');
                    footer.innerHTML="<h1>Including Footer</h1>";
                    footer.style.cssText = 'border:2px solid #9AB3CE;margin:10px;padding:10px;background:#E0E9F6';
                    document.body.appendChild(footer);
                }
            }
        </script>
        <base href="https://demo.dotcms.com">
    </head>
    <body></body>
</html>

Feel free to try out a few Page API calls for yourself!

On this page