Why authenticate and how?
The WordPress RESTful API was a major addition to the core ecosystem when it launched with WordPress 4.7. Having these endpoints opened up a slew of possibilities to be able to power the future of digital experiences. By using the REST API, developers are able to create native mobile and web applications that are driven by the WordPress backend. This is what’s referred to as a Headless WordPress site.
By default, anyone can make a GET request to any of the API endpoints for posts, pages, users, media, etc to garner data about your site and its information. WordPress Core has included a full list of REST API endpoints which can be found in the developer handbook here.. When it comes to creating posts or pages or adding information to your site via an API you don’t want any random person spamming your site with junk, and that is where authentication comes into play.
There’s a few options available for authentication. The easiest for development and testing purposes would be Basic Authentication, which requires that you send an appropriate username and password encoded in base64 with each request. You may have set up an .htpasswd file in conjunction with your .htaccess file in the past if you use Apache as your backend web server, and this is pretty similar to that, however instead of storing information in a hidden file, WordPress uses usernames and passwords from your database to authenticate. You can install the Basic Auth plugin from https://github.com/WP-API/Basic-Auth. Since this requires sending a username and password with every single request, I do not recommend using this in a production environment.
Another way of authenticating with the WordPress REST API would be to utilize JWT Authentication, or JSON Web Tokens, which is an open industry standard for representing claims securely between two parties. There’s a multitude of JWT Authentication plugins out there, but I typically see either the WP-API teams jwt-auth plugin used, which is still experimental, or the JWT Authentication for WP REST API plugin . Additionally Jonathan Dejong has also created a Simple JWT Authentication plugin, but they all seem to function on the same basic premises. Once this plugin is installed and configured you’ll need to generate a token to be able to prove that your application has the required permissions to access specific endpoints, such as showing all posts with the status of draft. By sending a POST request to the plugin’s token endpoint, containing a username and password combination, you’ll get back a token which you can use in the headers of future requests for authentication.
Testing Authentication and the REST API
So we’ve got our WordPress instance running, an authentication plugin setup and configured so now how do we make sure it is working as intended? Postman is my go to application for testing REST API calls. It’s interface is great, it has support for a multitude of platforms, and is just all around excellent, because let’s be real, who wants to write out long curl commands, manually setting headers, running the request again because you didn’t get all the information you needed. Sure that’s fine for a few people, but Postman simplifies the process tremendously.
When we make GET request to the posts endpoint we get back a JSON array that contains all of the posts on our site.
But if we change that GET to a POST we get a 401 Not Authorized error back, and this is because we haven’t authenticated our requests yet.
Basic Authentication with Postman
Let’s say the Basic Auth plugin is installed on our site, and we want to try to create a post. We can use a POST request to create a post within Postman. If you send a default POST request to the /wp-json/wp/v2/posts endpoint you’ll receive a 401 error. Click on the Authorization tab within Postman, and in the dropdown choose Basic Auth. To the right of that fill in your username and password you use for logging into the Admin Dashboard, and click Send.
You’ll get back a 400 response because we didn’t send any other data to WordPress to create a post.
If we fill in the required information as form-data on the Body tab in Postman, which in this case is Content, title, and excerpt we can create a draft post.
If you were to change the username or password in the Basic Auth settings you would get back a response telling you to reset your password. Just as a reminder, we don’t recommend the use of Basic Auth in production requests due to constantly having to pass your username and password.
JWT Authentication with Postman
JWT Authentication uses the Bearer authorization header rather than the Basic authorization header. To be able to generate the token for the header though we first have to make a request to the Token endpoint of our respective JWT Auth plugin to get this token, except you only need to pass in the username and password in the body of the request to generate the token. Once you have the token, you can then just send that in the headers instead of having to pass your username and password on every request.
On the Authorization tab in Postman, set the dropdown to No Auth, and change the request url to your JWT Authentication Token endpoint. For the body, set your username and password entries and submit your POST request to get your token.
Once you have that token, change the endpoint you want to authenticate against. Go back to the Authorization tab, change the dropdown from No Auth to Bearer and copy and paste your token into the Token field. Then create another post similar to what we did with the Basic Auth one. For the Body, ensure you have Content, title, and excerpt values and send your POST request. If everything is configured right you should get back a 200 response and see your new post’s JSON data in the bottom of Postman.
As Gutenberg becomes more prevalent in use throughout the WordPress community, I believe that REST API knowledge is going to become absolutely necessary. With different plugins extending WordPress’ core API, like Woocommerce’s API, this ll paves the way for some extremely slick digital experiences powered by WordPress as we move into the future. If you see anything I missed, or may not be 100% accurate about feel free to drop me a mention on Twitter, @wpdevlife.
Today I was working with a custom genesis theme that a customer had created for one of his clients, but none of his icons were showing. There was only a square box. This was pretty perplexing to me. Everything in the code looked correct. Icons were being called properly, and the CSS files were properly enqueued, and showing in the browser. The issue turned out to be a change that Font Awesome made in version 5.
Previously whenever utilizing an icon, the class would be something like class=”fa fa-instagram”. This is how the icons were being called in the theme code I was looking at and from everything I knew it was right. I checked the encoding of the database and created a new child theme. I even went so far as to not enqueue via WordPress and use the dirty @import statement. I downloaded the files locally and installed them on the site. Nothing I attempted was getting the icons to display. Only version 4 of Font Awesome worked. I was dead set on getting this resolved.
I decided to go to the WordPress.org plugin support forum for the Better Font Awesome plugin to see if there were other reported issues for the latest font. The issue turned out to be related to the different styles of icons that Font Awesome now provides.
Font Awesome allows for Solid, Regular, Light and Brand type of icons. Instead of using the fa class when loading the icons, you need to specify fas for solid, far for regular styling, and fal for light icons. If you’re going to be utilizing social media brands such as Instagram, Facebook, Youtube, etc. then you need to use the fab class. For example, if I wanted to load the Instagram icon, I would use <i class=”fab fa-instagram”></i> to load the icon. Any non brand icons are able to utilize the other three icon styles.
It is important to be aware of this change before updating any files that may be enqueuing Font Awesome version 4 to 5. At time of writing the latest version is 5.1.1. For a full list of icons, features, or to get Font Awesome Pro check out their website!
There exists within the WP CLI the scaffold command which allows you to easily create the base file and folder structure of some common WordPress features, like Plugins, post-types, or a theme based on Automattic’s _s. If you’re going experimenting with the new Gutenberg Editor slated for a Core Release in 5.0 there’s also the block generator. If you don’t currently utilize Boilerplates such as WPPB then using the scaffold feature of WP CLI can definitely help speed up your workflow
What does it do?
There’s multiple sub-commands for the scaffold command.
wp scaffold block – Generate the PHP, JS, and CSS files for creating your own Gutenberg block. I would definitely recommend this as a starting point for diving into creating custom blocks, especially since Gutenberg is slated for WordPress 5.0.
wp scaffold child-theme – If you use a framework such as Genesis, or Divi, or any other theme but need to get a child theme setup rapidly without manually copying/pasting files or creating them from scratch then this should shave some time off the initial setup.
wp scaffold plugin – Get a decent head start on developing a new plugin. I personally prefer using the WordPress Plugin Boilerplate because it gets setup for Object Orient Programming utilizing classes, so it gives you an even better headstart than scaffolding one.
wp scaffold plugin-tests – This will generate files for your plugin to run PHP Unit Testing on.
wp scaffold post-type – Whether you’re needing to get some post types added to your theme or for your plugin this command will generate all the necessary PHP code to register, and add a Custom Post Type to your plugin or theme, or just output the PHP code onto your Terminal for you to copy and paste it into a specific theme or plugin file.
wp scaffold taxonomy – Similar to the post-type command, this generates the PHP code necessary to setup custom taxonomies faster than having to manually type everything out, or saved somewhere as a template and then having to search and replace the necessary fields.
wp scaffold theme-test – Just like the plugin-tests this generates PHP Unit Test files around your theme.
wp scaffold _s – This works exactly like downloading a fresh file for Automattic’s Starter Theme Underscores or more simply put _s. You can pass all of the same arguments on the command line as you fill out on their website. It would be great to see WP CLI change the plugin scaffold command to use the WPPB setup that I’ve mentioned before, as their generator site works exactly the same as the _s website. If you need to create new themes and you prefer working with raw code starting from the bottom this is your best asset. I would like to see the addition of being able to choose some kind of CSS framework to add by default such as Bootstrap or Foundation as that could save additional time.
Wrapping it up.
For the full list of commands and more documentation I recommend reading over the Developer Handbook page.
Hopefully you find some usefulness to the scaffold command. Most local environments such as Wocker, or VVV will contain implementations of the WP CLI that are fully featured. Some web hosts that grant CLI access may turn off the scaffold command, but that’s due to developers scaffolding and programming locally before pushing things up with Git or another kind of development tool. WP CLI should be a part of any developer toolkit and can help speed up your workflow as you become more comfortable with it.
AWS has all kinds of amazing features that you can couple with your WordPress site. We’ve covered using the Simple E-mail Service for sending your WordPress e-mails and this time around we’ll be covering using the ElasticSearch service and 10up’s ElasticPress plugin. In my testing this greatly improved the search functionality and lessened the load on the web server’s MySQL instance. Note: Using ElasticSearch will increase your AWS bill.
Creating Your ElasticSearch Cluster
For the purposes of this article we’ll be utilizing some smaller-tier instances as noted above, this service does incur compute charges. Once you’re at the ElasticSearch Console create a New Domain.
On the next screen you’ll put in a domain, this doesn’t need to be your actual domain name but The name must start with a lowercase letter and must be between 3 and 28 characters. Valid characters are a-z (lowercase only), 0-9, and – (hyphen).
Last time I set this up, I think ElasticPress complained about using ElasticSearch 6.0, so choose 5.5.
To get good health you’ll want to utilize more than 1 instance. So we’ll go with 2 for now. You may need more depending on the amount of search traffic that your site gets. I’ve chosen the t2.small instances for now and this should be good for testing purposes in your staging environment. In production I would maybe add a few more instances or go with a larger EC2 instance type.
On the next page we’ll setup the Access Policy based on your server’s IP address to ensure that no one outside of your IP address can modify any indexes or delete any data.
Choose Public Access in the first section, and then in the Access Policy dropdown choose “Allow access to the domain from specific IP(s)” to configure an Access Policy.
Review the settings and then confirm to begin the process of creating the cluster. This usually takes about 10 minutes.
While your ElasticSearch cluster is spun up now is a good time to setup the ElasticPress plugin. If you have SSH access that allows you to git clone you can run git clone https://github.com/10up/ElasticPress.git elasticpress to clone the plugin directly into your site, or install it via the Plugin page.
Once installed and activated go to the ElasticPress dashboard to begin Setup. Grab your ElasticSearch hostname from the AWS Console as Endpoint.
Once that’s done you’re ready to index the site. You’ll need WP CLI access, or if your host doesn’t provide that, contact them to run wp elasticpress index –setup
ElasticSearch, while does present an additional cost to operating your site, can be beneficial to help improve your User Experience and help lessen the load on your database for an ecommerce store with a ton of products, or a general news site with thousands of articles.
If you see any issues feel free to let me know using the Contact page. If you find this useful feel free to share this on Social Media.