How to use WordPress as a headless CMS

WordPress communication

As the world’s most popular CMS, one would expect that WordPress is the most comprehensive application. It has everything that a business could possibly need for content management. In addition to the development team, there is an army of third-party developers creating plug-ins.

However, sometimes a business needs more than what’s in the box. WordPress might have the ideal content management features, but may not be sufficiently scalable for the business requirement. Perhaps the end-users need a tailored UI for their devices. It’s not obvious how to use WordPress to achieve this.

Here we take a look at using WordPress in a so-called “headless” mode [1]. Disconnecting the user interface and replacing it with bespoke code.

Why (on earth) would anyone want a headless CMS?

Actually, there are a few reasons:

  • Flexibility. Using a CMS in headless mode allows the developer to pick and choose the content management pieces they need. To integrate WordPress with another application perhaps, such as ERP.
  • Scalability. WordPress is ideal for small to medium implementations but there is a threshold when it begins to creak. By separating out the concerns, the application can be re-architected to suit the requirements and constraints.
  • Front-end capability. By re-developing the front-end from scratch, developers can make use of modern user interface code in a JavaScript framework, or tune the application for specific devices, such as Apple or Android mobiles and tablets.

Of course, a headless CMS brings with it many of the benefits of the full-blown application. WordPress is the most widely used CMS on the planet. It is supported on a range of operating systems, with regular maintenance releases and security patches. It only requires a MySQL database and a processor for the PHP scripting language.

What is still in the box?

After removing the front-end and publishing features, WordPress consists of some highly valuable code:

  • An API that can contain all of the back-end logic. In particular, the REST API [2] allows developers to interact using JSON objects. This is a powerful and industry-standard method of executing back end logic.
  • Content management, built into the WordPress back-end.
  • Data management using the WordPress database.
  • Editorial workflows, such as modification and approval.

How to use WordPress in headless mode

Setting up and building a headless WordPress CMS requires configuring a new implementation, applying a default theme and building a front-end to connect to the API. The steps are:

Install WordPress using the official instructions, following best practice guidelines:

  • Use a secure password
  • Hide the config files – wp-config.php and .htaccess
  • Change the database prefix from the default “wp_”

Define a default theme. The headless CMS will not benefit from WordPress themes, but the back-end still requires a notional theme to run. Create a default theme by adding two files: index.php and style.css [3]. These will contain basic information such as the theme name. Point index.php to the website’s home page. Finally, upload the default theme to the themes folder and use WordPress admin to activate it.

Develop the front-end code and connect with the API:

  • Use AJAX requests for the API calls
  • Use the fetch API to handle data requests, results and callbacks
  • Fetch can handle, for example, JSON or HTML responses

Use WordPress Advanced Custom Fields [4] to provide user interface functionality. Structure the API calls using the ACF to REST API plugin, this will correctly expose the end points for the REST API.

What are the caveats?

Out of the box, WordPress implements a good level of security. There are stories from disgruntled site owners, complaining about how their website was hacked. However, that’s usually a result of how the website was set up and managed.

In a headless environment, however, overall security becomes a headache for the application developer. The front end must be made bulletproof. It must handle the obvious risks, such as SQL injection through user input and deliberate crashing of the application. The overall wiring up of the application must be carried out with security in mind, including API calls and exception handling.

WordPress implements a system of roles to perform capabilities. These roles help to secure the site; they ensure that end users only have the access they need. The headless application must honour the WordPress role model, and manage the creation, management and implementation of roles.

Front-end display. Designing a new front-end will require more than mere development effort. Replacing the WordPress front-end will demand a user experience specialist to design the look and feel. Bear in mind that this will include content publishing, which is one of the major givens with a CMS.

Finally, if the website is to be dependent on search engine rankings, some attention needs to be given to being “search engine friendly”, another given with WordPress.

Headless WordPress – yes it’s possible … but

Given the caveats described, it is certainly possible to build a bespoke UI as a front-end to WordPress. There are substantial benefits from using its content management API and database. Flexibility and scalability are possible, without having to craft a new API. However there is a huge amount of UI design and development required, so it’s not for the faint-hearted.








Written by

Nathan Preedy

Nathan has been with since 2005 and has a background in Technical Support. He is passionate about helping customers find the best product for them and use it to its full potential.