Headless Architecture Simplified: How to Pull dotCMS Content with REST APIs

July 15, 2019
Jason Smith

Headless CMS systems like dotCMS have grown in popularity as companies have had to meet the content requirements of a multitude of devices and other embedded systems.

By decoupling the data and content from the front-end devices that consumers interact with, companies are able to offer a more consistent brand experience and maintain better control over their content creation. The key to taking full advantage of a headless CMS infrastructure, however, is the seamless interaction between the back-end where content is stored and the front-end devices that consumers use.

One of the ways to access content from dotCMS is with the use of REST APIs.

By default, dotCMS exposes a large set of REST endpoints that allows you to save, retrieve and manage content. The REST endpoints are also fully integrated with dotCMS permissions and authentication to ensure third-party systems and consumers only access what they are supposed to. REST APIs are particularly useful for brands that are looking to feed content to a large variety of third-party systems like digital signage, kiosks, Alexa Skills, and Single Page Apps.

How to Use REST APIs

The REST APIs in dotCMS 5.x have endpoints for the following: content types, content, Elasticsearch, images, pages, and many internal CMS configurations. For content, dotCMS has implemented full CRUD - the ability to create, read, update and delete using different HTTP methods. The REST APIs also support many different data formats such as JSON, XML,  FORM UrlEncoded, and HTML.

The dotCMS REST API documentation has everything a developer will need to build a well-formatted REST API request from scratch. Depending on the CMS configurations and use case, developers will need to build a request with the necessary authentication HTTP headers,  query parameters in the URL or endpoint, and the HTTP method that maps to the necessary CRUD operation. In SPAs written with JavaScript, it’s usually simple for developers to use HTTP Client libraries to integrate REST calls into an application and interact with back-end data seamlessly. The flexibility of RESTful standards means, however, that it’s possible to interact with the dotCMS web services using many other programming languages like Python or C++ on embedded systems.

An easier method, however, is to generate a content query automatically in the dotCMS back-end. You can do this by searching for the content and then clicking “Show Query”.


This will dynamically generate the REST API request that developers can use to integrate with any front-end systems that can parse JSON or XML.

API Authentication

The dotCMS web services are fully integrated with the permissions configured in the back-end. Along with the permissions for specific users, the REST APIs support many of the common authentication methods such as Basic Auth, JSON Web Tokens (JWT)  and front-end/back-end logins. If the request is sent without authentication, dotCMS will use the permissions assigned to the CMS Anonymous user. Although dotCMS allows HTTP access by default, it is recommended to only allow HTTPS access and to follow most of the security best practices.

Querying Elasticsearch

Elasticsearch is a RESTful search and analytics engine that is useful for enterprise companies with large volumes of data. In dotCMS Enterprise Editions, you can use native Elasticsearch queries via the REST API to search any content in the back-end because it's all automatically indexed by Elasticsearch. To generate an Elasticsearch query, it's a good idea to use the ES Search Tool on the dotCMS back-end.


Using Elasticsearch queries is a scalable and robust way to retrieve dynamic content for SPAs such as generating suggestions, document repositories and anything else that requires searching large volumes of data "on-the-fly".

Image Processing

In the dotCMS Enterprise editions, you can also do "on-the-fly" image manipulations via a RESTful interface. This feature allows content managers to upload only one image without the need to pre-edit it for specific devices or third-party systems. Instead, the front-end image request can modify the image as needed using URL path parameters. This could greatly reduce content duplication for large enterprise companies.

Pages and Layouts

Content as a Service using REST APIs is great for front-end developers using popular frameworks like Angular and React that work well with JSON, but when whole layouts need to be seen in context by not so tech savvy content managers, Layout as a Service may be a better solution, as layouts can be modified codelessly.

dotCMS’s Page REST API allows you to retrieve whole elements of any page as JSON or HTML. This means content managers can design pages using templates and a graphical user interface (GUI) within the dotCMS console. These entire layouts can then be retrieved using the REST API and render within JavaScript-driven apps. Thus, using Layout as a Service can empower content managers while virtually eliminating the need for any Java code.

The beauty here lies in the flexibility afforded to the developer. He or she might want to only retrieve content, like a list of news items, while building a custom layout. Alternatively, a developer might want to build a page with news items, with a pre-built layout, and so he or she can easily create a page, add a news listing widget and then, with the Layout as a Service, he or she can render that page using any JS framework.

For more information on building applications using the Page API, see Layout as a Service in dotCMS.

Lightweight Endpoints

Following the "No Code or Low Code" initiative, dotCMS has a Lightweight Endpoints feature that will allow front-end developers to create their on REST endpoints using only lightweight Velocity code. For companies with SPAs, this could give front-end developer more control while significantly decreasing the overhead and development time required by Java developers.

dotCMS: Seamless REST API Integration for Developers

Utilizing REST APIs allows the seamless integration between front-end systems and the dotCMS back-end. The endpoints exposed by dotCMS are flexible, scalable and intuitive for developers to use. Furthermore, the web services support many authentication methods and leverage the permission configurations of the CMS back-end. Enterprise companies with large volumes of data and content can further take advantage of the REST APIs by using native Elasticsearch queries and "on-the-fly" image manipulation.

BNP Paribas has been able to use the flexible API technology of dotCMS to integrate with many different systems and handle the variety of functions required of a rewards card. Using APIs allows BNP Paribas to offer customers access and manage their finances on the go with a new self-service portal.

And if you prefer Graphql, you’ll be happy to hear that dotCMS also offers complete Graphql support.

Jason Smith
Chief User Experience Officer

Take the next step! Schedule a Demo

Schedule a call with a dotCMS product specialist to see if dotCMS is right for you.

Request Demo

Filed Under:

apis rest api

Building Single Page Applications with dotCMS

SPAs aren’t the best fit in every situation, but when it comes to developing lightning fast user experiences within a single page, or building Progressive Web Apps (PWAs), or creating offline experiences, using a single page application is a no brainer.


Recommended Reading

Why Global Brands Need a Multi-tenant CMS

Maintaining or achieving a global presence requires effective use of resources, time and money. Single-tenant CMS solutions were once the go-to choices for enterprises to reach out to different market...

14 Benefits of Cloud Computing and Terminology Glossary to Get You Started

What is cloud computing, and what benefits does the cloud bring to brands who are entering into the IoT era?

Headless CMS vs Hybrid CMS: How dotCMS Goes Beyond Headless

What’s the difference between a headless CMS and a hybrid CMS, and which one is best suited for an enterprise?