We Need to Talk about the REST API: the non developer guide to the future of WordPress

25% of the web and growing – that’s the current distribution of WordPress

All types of projects are built with WordPress – from cooking blogs to corporate websites, to high traffic media sites to complicated CRM like projects and SaaS products. But is one platform really capable of doing all that well?

We’re all grown-ups, there are no fairy tales in software development and a one-solution-fits-all platform is nonexistent. So then how can this be?

Can there be a software platform that is perfect for both my grandma’s cooking blog and the complex website build of The Sun with hundreds of thousands of posts and a sophisticated flexible editorial management UX at the back?

This post is a modification of a talk called “We Need to Talk about The REST API” (Slides)  that I gave at WordCamp London 2016 on April 10, 2016. In this talk, I looked into how the REST API helps WordPress get out of its comfort zone to become a part of a bigger technology stack.

The REST API – the next important milestone for WordPress

WordPress is constantly growing. The way people use and perceive WordPress over the years changes. When it started it was just a blogging platform.

WordPress’ faces through the years
  • In 3.0, it started transforming into cms with the introduction of custom post types
  • In 3.8 after a major redesign of the admin area and with a sophisticated media library and editor on the back, it started being more and more appealing for bigger publishers, developers started using it for larger builds
  • With this, the business ecosystem around WordPress grew and developers started building complex services to extend it and compensate its flaws so it can work for big website builds (SEO, Security, Speed Optimization).
  • And at some point, more and more people started using it as an application Framework.
Screenshot 2016-04-05 14.29.55
A slide from 2014 State of the Word given by WordPress co-founder Matt Mullenweg at WordCamp San Francisco

Enter the WordPress REST API

WordPress 4.4 introduced the infrastructure for the REST API with the endpoints being planned to go in with the 4.7 release. The REST API is already developed as a featured plugin and used in production for many projects.

The REST API is the next phase and it will allow WordPress to be considered as a key element of larger, more complex projects. How? By providing a clear path to the WordPress content for any technology.

Why is this important?

If we think about WordPress as a real living and breathing creature, we need to admit – it’s got a lot of responsibilities. It needs to be nice to everyone! It needs to be modern, hype and tries to fit in with the other cool kids, it needs to be really bad ass and all powerful, strong and deep and sophisticated, but also very friendly and easy going to everyone new that would just like to say hello, have a quick convo and then go. It hosts huge parties for a lot of people every day and it does all the organising, preparation and execution alone!

It’s expected to be able to feed everyone and prepare hundreds of thousands of pieces of food, but at the top quality and very fast, otherwise the crowd will get impatient and will go eat somewhere else. But it also needs to entertain everyone while preparing the food, serving the food, cleaning after everyone, not allowing unwelcome guests to spoil the party all the while looking gorgeous in accordance to the latest trends.

And even though it’s got a Ph.D. these days, it needs to be friendly and obliging to everyone who still expects it to behave like it did in kindergarten. 

If WordPress was a creature, it would be burnt out, stretched and probably at the verge of suicide because of the impossible expectations towards it to be good at EVERYTHING and execute everything itself.

If you think about it, it’s not far from how a gifted, experienced, knowledgeable control freak feels when they get too much on their plate. You want to do everything, the way you know is the right way to do things and you insist on doing it all yourself, even though you know there are people out there that, if you just give them access, if you allow them, can help you deliver better results for the guests at your party.

The REST API is for WordPress that strike of genius that hits control freaks just before they break that allows them to finally let go.

The REST API will teach WordPress to Delegate

To be the best it can be in the kitchen, providing the essence of the party, while leaving the delivery of the food, the presentation to the guests, the entertainment and the security of the party to the cool kids, who can do it better.

WordPress as a headless CMS

On of the biggest strengths of WordPress is it’s easy to grasp, comprehensive and full-featured publishing backend that is also extendable and customizable with the use of plugins

Authors and editors love publishing with WordPress. They like the rich visual editor, the easy way to add and manipulate images, the tools, the distraction free mode and many more small but significant gems that streamline content creation.  WordPress is great for that.

The REST API will allow companies to develop products using WordPress just for its backend, separating it from the theming system, which nowadays, is used to create the front end – the design of the website, that the general audience sees.

WordPress is a monolithic CMS – it takes care of both the front end and the back end. The REST API will help to decouple the front end from the backend and WordPress can be used as just a publishing – not a site creating tool. Image source: “Talking to 25% of the web: a comprehensive guide to the WordPress REST API”

That way there is no limitations of the technologies used to build the front end. Remember these guys? They’ll be constant companions to WordPress from now on and together they’ll do great things!

Use WordPress as a content management system to feed multiple front ends

Using the API, developers can use the content from one or multiple WordPress instals and deliver it to multiple front ends. You can use the content of a single WordPress install to feed a website, a mobile app of your choice or a particular part of a larger website that has different content management systems and several different channels it delivers to.

WordPress as a headless CMS, delivering content to multiple platforms through the REST API. Image source: “Talking to 25% of the web: a comprehensive guide to the WordPress REST API”

That’s all great, but can you show us some examples?

Sure. Let’s look at some projects that use the REST API in production.

http://nomadbase.io is a browser app that aggregates geodata from social media channels and stores it in a WordPress database. The frontend is React and the next phase for the product is a React powered native iOS app that will reuse the code from the browser app.
http://ustwo.com – an award winning digital company, built their website with a WordPress backend and a React powered frontend.
The New York Times build a new Backbone interface to allow journalists to quickly produce content for its live coverage platform. Journalists send updates from the WordPress backend (or via Slack). The content can be read by JSON feeds. When journalists save, the content gets send to a custom service they call Invisible City. The REST API is used to allow that to happen via custom endpoints. WordPress displays the content on the frontend for SEO reasons, but the data is received via web socket from Invisible City and rendered via React.

Beyond the corporate website: The opportunities

  • Create context-specific solutions
  • Reusable, portable content
  • Separation of concerns
  • Familiar backend for authors and publishers
  • Integrate WordPress as one part of a content-authoring workflow

Growth pains: the challenges coming with the REST API

By now we saw the opportunities the REST API will provide for WordPress. But as any complicated technology advancement, it comes with it all sets of challenges and changes for parts of the WordPress ecosystem.

The front end features of WordPress core get lost

A REST API-driven website loses frontend features that are linked to the WordPress theme system, like menu management and post previews. Front end developers need to take responsibility for re-implementing features that come for free with WordPress. If they are not rebuilt, users must do without them. When writing project specifications for an API-driven project, it will become necessary to be very specific about the features that the client needs and not just assume that because they are in WordPress they are available. To solve this problem, we anticipate the emergence of REST API base themes that rebuild WordPress features on the frontend. These boilerplate themes will be written in different languages and will provide a starting point for frontend developers to build on.

WordPress site builders will lose control of the front end

I got into the WordPress Ecosystem from traditional web development and I was able to start building sites on my own very fast with a couple of experiments and after taking a few front end courses online. That meant that with WordPress core, a premium theme and a bit of CSS tweaks I could build a site quickly and for many, many, many things that I previously had needed a developer, I no longer needed one.

When we created the first website for A Day of REST – the first WordPress REST API conference, we decided to go with a theme because the development team at Human Made was very busy, we didn’t have allocated dev resources and we needed to get the site up fast. So in a way, we took advantage of everything the ecosystem had to offer – core, a premium events theme, our own knowledge of how to tweak it to fit our corporate identity and the content, that I and Siobhan were in charge of.

The A Day of REST site I built with Siobhan

In less than 2 days we had a site. But it wasn’t great. And not only it was not great, it wasn’t ideal for a conference dedicated to the REST API to not utilize the technology for its own website.

So Joe rebuilt the website in a weekend, using the REST API and a React power theme designed by Noel. He also open sourced the code and created a cute little widget at the bottom of each page that allowed developers to see the API requests for each of the pages. Brilliant!

The new FeelingRestful.com with a WordPress backend and a custom React.js front end.

The problem is Siobhan and I did not realise the impact the theme would have on our publishing processes until Joe wrote about it and we started using the new site.

Overnight, we ended up unable to preview posts, manipulate images within posts, create and edit menus and do any type of CSS tweaks. Even the smallest changes needed a developer with enough JavaScript/REST API knowledge. 

When using the REST API, it’s important to take this into account. That’s especially important when creating specifications for projects using the REST API for clients who might be used to the front end manipulating features of WordPress. Front end developers will need to rebuilt those as they are not yet a part of what comes packages with the REST API.

And this is, actually, one of the deal breakers for the merge of the API in WordPress core.

No more layout building from the visual editor

To be able to deliver data to multiple devices, the REST API will require the content to not be over formatted in the WordPress admin. That’s why REST API driven sites will not rely on WYSIWYG in TinyMCE for page layouts. Content will be added through modular page builders that format the content in a different way.

Progressive enhancement 😱

Developers need to address the issues of some browsers not supporting JavaScript ensure that the web stays accessible. It might be costly for some projects, but it’s important to not overlook this. Otherwise, you’ll get Rarst even more grumpy than he usually is. And we don’t want that because we like Rarst.

What will change?

  • WordPress will become just one layer of a larger technology stack
  • WordPress will be used for huge, enterprise projects
  • WordPress developers will specialize in backend development
  • WordPress will (finally) be adopted outside of the PHP communities
  • New, funnelled, role-based admin interfaces will become much more common

What will NOT change?

  • Themes and theme shops are not going anywhere
  • WordPress will still be used for both cooking blogs and The SUN
  • Backwards compatibility will not be forgotten
  • WordPress’ mission will remain the same: To Democratise Publishing



Learn more about the REST API:


A very special thank you to Scott Evans for the amazing panicked, burnt out Wapuu and to the creative community of wapuu designers for their inspiring work.