This is a transcript of the talk I gave at A Day of REST Boston 2017. It’s a short version of my talk The WordPress REST API: A Guide for Non-Developers presented at WordCamp US 2016. You can watch the video from that on WordPress.tv.
Great expectations: Prepare your non-developers for a REST API project – slides and transcript
Today is all about learning how far you can go with the REST API. All the amazing opportunities it provides. All the paths to get to building the projects of the future on WordPress. It’s a much-needed breath of fresh air for our favorite cms.
Our favorite cms that is trying to solve too many problems on its own and ending up failing at quite a bit of the tasks – performance, security, scale…
If WordPress was a creature it would be at the verge of breaking down, because of the impossible expectations towards it to be good at EVERYTHING and do everything itself.
It’s exhausting to want everything from a single platform.
So it’s the REST API to the rescue. The REST API will help WordPress learn to delegate. With the help of the REST API, WordPress will be able to focus on what it does best – providing amazing space for authors and editors to create content. The REST API will help WordPress to finally stop worrying about the front end and let the cool kids developers love playing with deal with it.
But as any growth process, there are some growth pains that we need to be aware of when you decide to build projects with the REST API.
With the decoupling of the front end and back end of WordPress, the features allowing you to customise the way your site looks will be lost, unless special efforts are made towards re-building them.
The “Appearance” settings – menus, background, the editor, the customiser plus the previews of posts – the link between the front and backend, need to be specifically built within a REST API theme to be available.
That, as you might imagine, could be a problem for a lot of people who are used to building a website with WordPress using just themes, plugins and implementing a bit of code here and there.
The major difference between building a WordPress project and a custom project is that the chance of your PM or client to already have expectations on what they can do with their future site are about 100%.
They will have certain expectations about how the editor will work, about their abilities to tweak things, preview things, manage menus, create and modify layouts. The great thing about WordPress is that even if you’re not a developer you have the ability to create a site from scratch. And maybe a lot of them will have.
So you might have seen Siobhan and myself run around this morning and during lunch time. We’re a part of your A Day of REST organizing team. We both have been involved with WordPress for quite a while and know more than how to just create content. Siobhan’s been using it for years, taking advantage of all the opportunities it provided and playing around themes and plugins. I came to IT from marketing and public relations, spent 5 years as a project manager in a publishing companies, telling developers what to do without any idea of how on earth they’d do it. But for me discovering WordPress in 2011 was mind blowing because I no longer needed you lot. I did not need a developer to build a website anymore. Until this happened :)
This story illustrates what happens when you don’t prepare your non development team for a rest api project and second, and more important, this is me giving feedback to the developers of the project, who also happen to be my bosses, about the project.
Back to site builders. Those people building WP sites with no code. Siobhan and I are site builders. The Do it yourself kind, that besides creating content, were also used to using and tweaking themes. So when the time came to organise A Day of REST, which was our responsibility, we had to decide how to organise the website.
At that time, the development team at Human Made was super busy and we had to find a fast solution to put the site up so we could announce the conference.
When we created the first website for A Day of REST London, we decided to go with a theme to save time and resources. So in a way, we took advantage of everything the WordPress ecosystem had to offer – WordPress core, a premium events theme, our own knowledge of how to tweak it to fit our corporate identity. 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 use the technology for its own website. There were people on Twitter yapping about things that were not obvious and I could not understand related to performance and usability but I decided that if our dev team suddenly decided that their arguments were valid, then that was a justification enough to build the site with a react theme. For me, that meant that Twitter would shut up and I’ll be able to go on and happily continue marketing my event. Little did I know…
So Joe rebuilt the website in a weekend, using the REST API and a React power theme designed by Noel. He also opensourced 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. They quickly launched the site reusing the content we already had in the old one. Brilliant!
To make his point and share the experience, Joe wrote a post explaining why he rebuilt the theme, how he did it, how we’re open sourcing it so everyone can watch and learn (yay) and also – what’s missing from the site in terms of functionality compared to a normal WordPress site.
And it is in this post exactly that Siobhan and I found out about the impact the change would have on our publishing and site management processes.
Overnight, we ended up unable to preview posts, manipulate images within posts, create and edit menus and do any type of CSS tweaks. Needless to say we couldn’t add plugins but the most impactful thing were the limitations that were introduced when managing content. Even the smallest changes needed a developer with enough JavaScript/REST API knowledge. We waited days to get a new menu item added, or to add the sponsor logos to the front page, we couldn’t insert links in pages that were not built using the modular page builder on the backend.
So even something as simple as adding a link to a page became a problem.
I don’t need to mention how the control freak, do it yourself wannabe inside of me was feeling. For years I’ve always been able to figure something out when it came to using WordPress. This time, my hands were tight. I was back to this sorry miserable 2007 state where any change on my website needed a developer.
Siobhan, as an accomplished, published author, was more eloquent. In a WordPress company consisting of 90% developers, we were involuntary victims of the miscommunication about what the cool new theme would take away from us.
So going back to that particular challenge – a sound advice – be sure to prepare detailed specifications for your clients when proposing a REST API project. Or make sure they know what they are asking for when they ask you to build them a project with it. Don’t let them believe that just because it’s WordPress, it’s going to have all the core features. Be aware of the decoupling of the front and backend. Talk to your non developers about it. Otherwise they’ll end up trolling you from all sorts of different stages for the rest of your life.
Think about everything you take for granted. Because let’s face it – you’re the coding superstars of WordPress – the people who are a bit confused about how user features in the admin work because you never use them. You’re too cool for the admin. It’s command line or bust.
So it all comes down to this: be kind to the people you work with. Don’t throw them in the ocean to teach them to swim. Help them understand what you’re building together.
Start here: The REST API white paper Siobhan wrote with some peeps from the REST API team.
Thank you!
