Interacting with the WP-REST API – an overview.
If your site uses PHP to respond to something your users do, a request will go to the server to process that change and then the page will refresh with the change activated.
You can imagine the advantages this can bring: cutting out all those server requests can make your site run much faster and can give you the flexibility to create web-based applications that work a lot like desktop programs.
Creating and editing menus
Creating and editing widgets
Updating plugins and themes
Using the Customizer.
It’s only when you click on the Publish, Update or Save Changes buttons that PHP kicks in, permanent saves are made to the database and the admin screen refreshes, which it’s why it’s so important to click those buttons.
Let’s take a look at how you insert scripts to your themes and plugins and how you call external libraries.
1. Adding Scripts to Plugins and Themes – the Right Way
In WordPress, you shouldn’t call scripts from the <head> section, tempted as you may be to add that to your theme’s header.php file or hook it to wp_head in your plugins. There is a correct way of adding scripts in WordPress, which is called enqueueing.
Enqueueing scripts is better for two main reasons:
It avoids adding a script more than once, as WordPress won’t load the same script twice if it’s enqueued twice.
It manages dependencies and order of adding scripts for you: so if one script (e.g. one you’ve written using jQuery) needs another one (e.g. jQuery) to be loaded, then it will do so in the right order.
Note that jQuery (amongst others) is already enqueued within WordPress, so you don’t need to enqueue it – just enqueue your own scripts and set jQuery as a dependency.
To enqueue scripts you use the wp_enqueue_script() function, placing this inside your own function which you then hook to the wp_enqueue_scripts hook. If you want to load a script in the admin screens, you use the wp_enqueue_scripts() function in the same way but hook your function to the admin_enqueue_styles hook.
So to load a script in your theme, you would use this code:
This adds a script called my-script.js, which is stored in the scripts filter in your theme. I always add scripts in a separate folder as it keeps things organized, and is particularly useful if you need to add ore than one script. This script is dependant on jQuery and will be loaded on every page.
Sometimes you might not want to register your script on every page, in which case you use two separate functions: wp_register_script and wp_enqueue_script(). For full details see Daniel Pataki’s tutorial on enqueueing scripts the right way.
Methods. A method is something that happens to an object. It’s similar to a function in PHP – when you create a function, you then call it using a method, or you can call a built-in method. You can recognise a method by the brackets that follow its name.
Properties. Properties are the values associated with an object. Properties are also used in PHP (with classes), but they work differently.
In the code above I’ve created a variable (an object) called animal. That has an array of properties, type and color, each of which has a value. I then use the document.write() method to output the value of the type property to the web page.
3. Using jQuery to Add Effects and Animations
A powerful aspect of jQuery is in the way it lets you select elements by using their CSS. So for example you would select an element with the id of banner like this:
You could then take that selector and apply a method to it, like so:
This takes the element with the ID of banner and adds a <h1> tag to it with contents, using the append() method.
jQuery itself has a number of methods that you can use to create animations and effects. Examples include adding content, dynamically changing css, hiding and deploying elements, making elements move and change size: for a full list, see the jQuery website.
jQuery uses a few simple concepts that you’ll use in your code:
selectors: you’ll need to select an element (or multiple elements) on the page so that you can do something with them.
filters: you can filter your selection, so that only certain elements are selected (such as odd numbered elements).
events: jQuery can react to specific events such as a mouse click or keyboard press. You can combine these with selectors so that something happens when a specific link is clicked, for example.
variables: define variables based on selections, inputs or values you define, and then manipulate those variables.
effects: once you’ve selected something, or an event has triggered, you can then apply an effect to the element selected. Effects include fading in and out, sliding elements up and down, or toggling between these.
animations: using the animate() property, you can animate any CSS property that accepts numeric values, for example text size, position of an element or opacity.
And if the jQuery methods and effects aren’t enough for you, then you can use the jQuery UI library, which gives you access to even more interactions and effects.
So each entry in your database is an object. It has a label (a string) and a value. Your site will also have data which consists of arrays, and arrays within arrays.
JSON can handle all of this. Just as in PHP, a value can be a string, a number, an array (here’s where nested arrays come in), or a boolean value. It can also be an object.
Understanding how to use JSON with the REST API in detail is beyond the scope of this post, but here’s an introduction to getting started:
Tools. The first thing you’ll need is an HTTP client that will interact with the API. The most popular one I’ve come across is Postman for Chrome. You then work in this client.
Discovery. Before interacting with your site, you’ll need to check whether the site has the REST API enabled. There’s more than one way of doing this, which you can learn about in the REST API documentation.
Authentication. For security reasons, you’ll need to use authentication. You can do this using one of three methods: cookie authentication for themes and plugins running on the site; oAuth authentication for external applications; and basic authentication for external clients during development (not recommended for production as it’s less secure). Find out how this works on the REST API site.
Fetching data. You do this using the GET command. This fetches all of the data associated with a post but doesn’t output anything. So for example to get all of the posts in a site I would use:
Or to get just one post, with the ID of 100, I would use:
Editing and posting data. You can do more than just fetch data: the PUT command lets you edit data and the POST command lets you post new data. Think of putting like updating a post and posting like publishing one. To start with I recommend using the API to fetch data, in case you make mistakes and lose your data.
Outputting and manipulating data. Once you’ve used the GET command to fetch data, it’s available for you to output and manipulate. The REST API gives you a number of functions you can use to work with and filter JSON objects: one of the most user-friendly resources I’ve found that demonstrates this is Josh Pollock’s ebook on the WP-REST API.