My Struggle to Learn How the WordPress REST API Works

Earlier today, I watched a free presentation on how to use the WordPress REST API by Rachael Baker via WPSessions. If you missed it, you can watch the recording for $9.

As I watched the presentation, it was clear that no matter how many tutorials I read, WordCamp sessions I attend, and videos I watch, I won’t be able to grasp the API until I use products built with it. I’m not a developer and the REST API is developer centric technology.

What I Think the REST API Is

Based on what I’ve learned so far, I’ve figured out that the API provides a series of end points which are specific parts of WordPress. These end points can be connected to and manipulated through the REST API.

It’s this API that opens up a slew of new opportunities for application developers to send and receive data. This is what allows a developer to build an app that connects to WordPress with minimal code.

Learning Custom Post Types

In 2010, there were a lot of requests for tutorials on how to give specific posts a unique style. When Custom Post Types were introduced in WordPress 3.0, I was excited because I thought they would provide the ability to create custom styles for posts.

Looking back, some of the requests are due to the post_class() function added in WordPress 2.7 that provides the ability to use CSS to style a post. It took a few years to rewire my brain to not think of Custom Post Types this way.

When I described how long it took to figure out Custom Post Types on Twitter, Justin Tadlock responded, that end users should have never been introduced to the term post type.

Reviewing Products Helps Connect the Dots

I didn’t fully comprehend Custom Post Types until I reviewed several WordPress products that utilized them. After awhile, I was able to connect the dots between what I saw in the WordPress backend and what appeared on the front end.

I think the same thing will happen when the REST API is added to WordPress core. I’ll be able to connect the dots and figure out how it works by reviewing products that use it.


19 responses to “My Struggle to Learn How the WordPress REST API Works”

  1. I think the rest API will really start to show for end users when you start seeing a lot of themes use it for headless WP. I wouldn’t be surprised if WP admin starts using this as well (much more so than it does now). You’ll start to see a lot more interactive parts of the site that don’t require a page refresh, that refresh data automatically, that keep you very connected to the site.

    I do have to disagree on the sentiment that end users should have never been exposed to the term “custom post type.” I don’t think it was helpful to use the term “post,” as something like “custom content type” would be much more accurate and less confusing. However, I always try and educate clients on how things work behind the scene, as it can sometimes help them see why some tasks take as many hours as they do as well as help them know what I as the developer have to work with. Not all of them want those details, but I find the ones that do have much less stress and feel more pride in their site. :)

  2. The REST api will make sense for everyone when Themes and app leveraging it will be showcased. There is still only few tutorials on how to use it for now.
    When you look at the CPT or the customizer, there are still developer tools. Although with plugins like ACF or Pods, more and more people will be able to use it.
    These API are definitely great for developers but what matters to end users it’s what it does for them and how they can use it.

  3. I must admit, I watched the presentation. Two things were obvious. One was that, as a long time programmer in PHP and Javascript, this was way above my head, AND that the presentation only brushed the surface. It was clear that a whole bunch of detail was missed out. I think that the developers, as represented by the awesome Rachel Baker, need to think long and hard about HOW they show us how to use the API, and what I watched yesterday was NOT the way to go. They need to build a demo front end that is fully commented in code so that we can take it apart and see it work.

  4. I’ve been using the WP-API for a custom project where I created Custom Post Types with Advanced Custom Fields and it is really simple to pull all the data that I need. I was able to modify ajax scripts I already had to pull the data and parse it out.

    The project I am working on has a google map integration that will pull some of the information from these posts, and the pins themselves will use the data provided from the WP backend. It is really awesome how far the API has come and I look forward to using it more in the future.

    • Luke – I did something very similar, integrated it to a site that was writing to a google map using PHP & Javascript, (600 + posts with co-ordinates, different categories etc…)

      Recoded the map, using AJAX to get the JSON feeds from the API, and write directly to the map. Huge increase in speed. And flexibility. I can pull any of the custom fields, I have even pop-up booking widgets triggering from buttons in the resulting Google Map Infowindows.

      When you get your head around it, its a fantastic resource. Awesome.

  5. Am I the only person who sees the WP REST API as counter-useful to WordPress’ big-picture market share aspirations? As @loganyott phrased it above, this “headless WordPress” is … not really WordPress at all; it’s just PHP and MySQL being accessed by something else.

    • I find myself disagreeing with this ‘headless’ view. WordPress has become an application, as opposed to just a blog platform (long since moved on from) and a CMS. It is bloated with legacy features and code. As I understand it, and I could easily be wrong, plugins and themes can be used with the REST API. Certainly, the demo I saw yesterday did just that. The back end does not change, and it is that part of WordPress that is most useful.

      Now we see lots of basic themes and a spreading array of specialist themes. I use a theme framework, Ultimatum Theme, that already de-couples much of the WordPress front end. They are chomping at the bit to be able to use a fully fledged REST API, to be able to remove the last vestiges of the WordPress front end. The REST API allows developers to make customer centric solutions for both desktop and mobile, where integration and flexibility is the key.

      As a developer, it is frustrating to spend 90% of the project development time on finessing WordPress Themes, Plugins and HTML/CSS/PHP/JS code. As it is, I hope that WP REST API V2 will appear as ‘stable’ within 3 months, but I know that it will not progress into core until at least WP4.4 (December 2015?).

      • Trevor, thanks for your opinion … and even more for your specificity. I hope you’ll be OK with me being specific too.

        I agree that developers will benefit from REST. No question; faster easier development is in the cards. My concern is that WordPress itself will lose relevancy. I know, that’s an incredibly high-level view of things, but that’s where I’m coming from; DEVELOPERS “knowing they are using WordPress-y tools” is far less important in the larger scheme of things than the world (you know … PEOPLE … who care about BRANDS) knowing it.

        • Hi. Thinking one moment from my POV. I have never been asked by a client to install a WordPress site. Those clients that I have worked for have been in 2 camps. One (most common) already have WordPress and are most concerned to keep the data in the database and the ease of use of the backend, but want totally different front end and often additional functionality. Whilst they will not see that I might use the WP REST API, my doing so will not impact negatively on their needs. The other set of customers have a need for an all new site, no legacy required. WP REST API will not impact negatively on that either. Does WordPress NEED a public image and branding, that is, for the users of the website? How many people visiting a website realize they are visiting a WordPress powered website, or even care? Will WordPress become irrelevant? I doubt it.

          • I hear you. And while I DO know of real-world “gimme WordPress” examples … a shocking and growing number of them, by the way … and have seen that personally, I get your point.

            But if we are to assume that developers drive this conversation we must also accept that developers are a fickle bunch; next years tools will be BETTER! WOW! COOL! LOOKIT ME NOW!

            That’s not a sustainable market. 50% of all websites last year and 23.x% of all websites don’t come from developers, they come from people playing at being web site designers using accessible, good-enough tools, and that describes what WordPress “is”. The REST thing is a whole ‘nother discussion. What happens when WIX and Squarespace build calls to WordPress (assuming they can think of a reason to bother)? Market shift.

            I’ll stop now ;-)

    • I think the assumption there is that the API’s primary concern is making WordPress headless – and it’s not. The REST API will be the best thing that has happened for the long-term goals of WordPress in a long, long time.

  6. It doesn’t have to be complicated, but yes, it is developer-centric overall.

    Essentially, the API provides a standard means of accessing and/or manipulating the data sitting in a WordPress instance. This seems smaller than it actually is.

    Consider a theme that wants to, say, display posts without making a refresh to go to the next page, which would be the traditional way to do it. Obviously, for such a case, you can roll-your-own endpoint to access the data you need, and in the past, this is what most solutions have done. You make a PHP function to return the data you need, and some Javascript in the theme to access that endpoint. A standardized API provides a standard set of endpoints for doing this sort of thing, all you have to write is the Javascript, which is actually quite easy to do.

    Consider a plugin that wants to, say, take input from a form and save it into the database, maybe using a custom post type. The plugin has to have code to get the data from the form, insert the post, sanitize, validate, and so on. With an API that will let you write posts, you can use that API to do all the grunt work. All you do is to write the form and some JS and maybe also do some authorization checks and such.

    A standard means for getting and manipulating the data can indeed let you redo the whole admin side if you want. It would make it very simple to do something like front-end-editing. Or maybe to drag and drop and rearrange the widgets live. But the point is that it’s rather generic and standard, allowing for a wide variety of uses.

    It also eliminates a lot of the security problems inherent to roll-your-own code to do essentially the same things, because plugin and theme authors have proven, time and again, that they’re actually not very good at PHP, and that security is hard to get right. One standard place to manipulate the data, with security built into it, is probably a good thing.

    • I think the best example for Jeffro might be to see the code to get and update post meta via XML-RPC vs code to do the exact same things via REST.

      Sadly I don’t have a handy example, but bet someone does.

      It’s not that either chunk of code be easily readable by a non-programmer, but I think it’ll be obvious how much simpler and more readable by REST example is.

  7. A pretty common use-case is going to be creating native mobile apps which work agains the API. Creating a customized mobile experience with WordPress on the server-side is going to be easier than ever. You might be able to think of it as “remote theming”.

    Another use-case might be server-to-server communications. You could easily create a network of sites, hosted on completely separate servers, which communicate with each other, pass information back and forth, sync with each other in various ways.

    Yes, you can do some of that now with the old XML-RPC APIs, but the new APIs will be more comprehensive, and more consistently designed.

    I think any fears of this “replacing” regular WP use are unfounded. This is an addition to its existing strengths. There may be specific niche products or services which use this as a basis to “replace” the existing front-end and/or back-end, but I don’t see that weakening WordPress as a whole in any way.

    The main thing that this is replacing is the old XML-RPC interface. As someone who put a lot of work into that area in the early days, I’d say that this is a good thing. The XML-RPC APIs were a mess — not WP’s fault (or mine), it was that way already. It was three layers, haphazardly built one atop the other, starting with the original (and very limited) Blogger API, then extended with the metaWeblog API (an attempt to create a better, more universal standard), and then further extended by the Movable Type API (which filled a few more gaps missed by metaWeblog). Furthermore, the XML-RPC protocol itself was a bit ugly. But at the time, JavaScript was still a bit of a mess, JSON was barely a thing yet (hardly anybody had heard of it), and while there were various things happening with remote requests in the browser, the term AJAX was still on the horizon.


Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.