Half-Elf on Tech

Thoughts From a Professional Lesbian

Tag: rest api

  • Vulnerability Reports Miss The Mark

    Vulnerability Reports Miss The Mark

    Lately I’ve been getting a lot of ‘vulnerability’ reports.

    I use the term loosely because the reality is these are not actually serious vulnerabilities. A couple months ago I started getting a lot of weird reports like this:

    A FLAW FOUND ON YOUR WEBSITE!

    Website Security Vulnerability Notification

    Hello, a security researcher reported a security vulnerability affecting [your] website via [company] coordinated and responsible disclosure program:

    Those can be super scary! Is there really a massive issue?

    No. But I know why it feels that way. And frankly I think a lot of these people are targeting the wrong group. Let’s get into it.

    Scare Tactics

    In the case of all the ones I got, there was only one that I felt actually was. But first, here’s what people reported:

    • The PHPInfo Page was public
    • Directory indexing
    • People can list users (aka User Name disclosures) via the REST API
    • Your xmlrpc is showing
    • Incomplete SSL Protection
    • Your email records allow spoofing/DMARC compliance

    The last one? Absolutely an issue. I thanked that person and kicked them some money. But the others? They’re issues, but they’re also incredibly minor! Heck, this user name listing ‘vulnerability’ does not take the following into consideration:

    1. It’s on a site where every author has a page
    2. We have an ‘about us’ page that lists everyone anyway
    3. Strong passwords are enforced
    4. We have a firewall

    The only way I could really improve that would be to enforce 2FA, which I’m contemplating for admins. But that begs the question… is this a vulnerability?

    Okay, let’s ask why does this work? It’s known that WordPress has a REST API. This API can be used to list public information about registered users. Now the API does ‘expose’ the user data for everyone who’s authored a public post that is shown in the REST API. Posts and pages and some custom post types included. If the user hasn’t authored posts, you won’t have permission. So again, we’re only able to list public authors. Okay.

    Could that be bad? Sure. In the same way having a front door could be bad if someone kicked it in. But ‘security’ isn’t why I would ever consider blocking that. We literally list all the authors publicly already. If someone wants to use wp-json to grab them, cool. It only shows public information we displayed already, after all.

    Why would I consider blocking? To ensure stability. That is, people hammering my site to find out that I’m not user on HalfElf (surprise!) makes my site slower. But… I have a firewall and Mod_Security, and IP Tables, which means if you hit my site enough, it’ll block you. Also a lot of stuff is cached, like it should be. Which means this is not a ‘vulnerability’ but more of a ‘best practice notice’ in my opinion.

    And finally … FFS why are you telling individual site owners this!? If you really think it’s a security issue, take it up with WordPress!

    How Do You Stop Them?

    Well, generally you fix the ‘issues.’ Even if you think it’s full of shit, you fix it. So okay, what do we do?

    PHPInfo? Locked it down. I use it for regular checks of other things. If you’re not, just delete it.

    Directory Indexing? I put this at the top of my .htaccess (and yes, you should, I’d removed it for some tests):

    ### Prevent Directory Browsing ###
    Options All -Indexes

    XMLRPC? I said “Nope, not gonna change.” Because I use the WordPress iOS App.

    SSL? You’ll want to check your setup on things like SSL Checker or Immuniweb or SSL Labs. I found SerpWorx’s tool to be invaluable for spelling out what was missing. The easiest by far was SecurityHeaders.com. For that, I ended up adding this to my .htaccess:

    ### Extra Security
    <IfModule mod_headers.c>
    	Header set Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
    	Header set X-XSS-Protection "1; mode=block"
    	Header always append X-Frame-Options SAMEORIGIN
    	Header set X-Content-Type-Options nosniff
    	Header always set Expect-CT "max-age=7776000, enforce"
    	Header set Referrer-Policy "same-origin"
    	Header always set Permissions-Policy "geolocation=(); midi=();notifications=();push=();sync-xhr=();accelerometer=(); gyroscope=(); magnetometer=(); payment=(); camera=(); microphone=();usb=(); xr=();speaker=(self);vibrate=();fullscreen=(self);"
    </IfModule>

    The one thing I left out was Content-Security-Policy because that one is crazy complex and needs a lot of testing since a lot of content on the site is remote and needs special rules.

    Email/DMARC? That took a lot longer, and I had to talk to my email provider to sort it out. But you can run your domain through the MXToolBox checker and see what you’re missing. It’s going to make you cry. Email sucks.

    Okay but I wanna hide users!

    I hear you. You can do this in .htaccess:

    ### Block User ID Phishing Requests
    <IfModule mod_rewrite.c>
        RedirectMatch 301 ^/wp-json/wp/v2/users(.*) /about-us/
    
    	RewriteCond %{REQUEST_URI} !^/wp-admin [NC]
    	RewriteCond %{QUERY_STRING} author=\d
    	RewriteRule ^ /about-us/ [L,R=301]
    
        RewriteCond %{QUERY_STRING} rest_route=/(.*) [NC]
        RewriteRule (.*) /wp-json/%1 [L,R=301,QSD]
    </IfModule>

    Now. This means on that site if you go to example.com/?author=1 you will not go to someone’s page. But if you go to example.com/author/ipstenu/ you still would. Which IMO points out how stupid that ‘vulnerability’ is. Yes, I am aware you can see the authors. Oooooh. You’re supposed to!

    Conclusion?

    A lot of those vulnerability emails are bullshit. I politely reply “Thank you for your concern however we are not blocking access to that because the API is used by other things. It’s considered to be public knowledge anyway.” I may end up writing a form letter.

    And the sucky thing is that one of the sites that collects all that stuff relies only on the reporter to determine if it’s resolved. Both issues they have for the domain in question? 100% resolved. But they say ‘unpatched’ … probably because I told both reporters I’m not paying them.

    I added this to my profile:

    We do not accept reports of basic WordPress functionality, such as the Rest API being active, the use of xmlrpc.php, the enumeration of users, etc. Those are an acceptable risk. Please don’t bother reporting them, they should be addressed with WordPress directly, not end users.

    By the way. The bug bounty program that keeps emailing me? Uses WordPress. And guess who’s site has /wp-json/wp/v2/users available to list all their public authors? Yeah. Because it’s not a goddamn major issue.

    I know someone’s gonna point out it could be a major issue. Sure. Like having a window means your house or car could get broken into. That doesn’t mean you remove all the windows!

  • Flash Briefing JSON Feed

    Flash Briefing JSON Feed

    The other day I mentioned a ‘solution’ to my problem of video enclosures would also be to use a JSON feed. As much as I’d like to tell you just to use JSON feed, you can’t because their specs don’t match Amazon’s.

    The creation of a JSON Feed that does match their specs is somewhat peculiar, but still straightforward. I went with making a JSON API output instead of making true feed, since frankly I don’t think Amazon’s all that consistent with their own spec, and I’ll need to tweak it later. I’d like to do so without breaking everything else.

    The Code

    class MYSITE_Alexa_Skills {
    
    	/**
    	 * Constructor
    	 */
    	public function __construct() {
    		add_action( 'rest_api_init', array( $this, 'rest_api_init') );
    	}
    
    	/**
    	 * Rest API init
    	 *
    	 * Creates callbacks
    	 *   - /MYSITE/v1/alexa-skills/briefing
    	 */
    	public function rest_api_init() {
    
    		// Skills
    		register_rest_route( 'MYSITE/v1', '/alexa-skills/briefing/', array(
    			'methods' => 'GET',
    			'callback' => array( $this, 'flash_briefing_rest_api_callback' ),
    		) );
    	}
    
    	/**
    	 * Rest API Callback for Flash Briefing
    	 */
    	public function flash_briefing_rest_api_callback( $data ) {
    		$response = $this->flash_briefing();
    		return $response;
    	}
    
    	/**
    	 * Generate the Flash Briefing output
    	 */
    	public function flash_briefing() {
    		$query = new WP_Query( array( 'numberposts' => '10' ) );
    		if ( $query->have_posts() ) {
    			while ( $query->have_posts() ) {
    				$query->the_post();
    
    				$response = array(
    					'uid'            => get_the_permalink(),
    					'updateDate'     => get_post_modified_time( 'Y-m-d\TH:i:s.\0\Z' ),
    					'titleText'      => get_the_title(),
    					'mainText'       => get_the_excerpt(),
    					'redirectionUrl' => home_url(),
    				);
    
    				$responses[] = $response;
    			}
    			wp_reset_postdata();
    		}
    
    		if ( count( $responses ) === 1 ) $responses = $responses[0];
    
    		return $responses;
    	}
    }
    new MYSITE_Alexa_Skills();
    

    Some Notes…

    This is built out with the assumption I will later be adding more information and skills to this site. That’s why the class is named for the skills in general and has the rest route set up for sub-routines already. If that’s not on your to-do, you can simplify.

    I also made the point to strip out the possibility of a StreamURL, which I don’t plan to use at all on this site. If you do, I recommend having a look at VoiceWP’s briefing.php file which does a nice job with handling that.

  • REST API On This Day

    REST API On This Day

    After making a simple REST API output that showed the date (and time since) the last death listed on a site, I had an idea. What if I could list everyone who died on a specific day? I had that data after all, so why not.

    A Word About Evolution of Code

    Over time, the code behind my “Bury Your Characters” plugin evolved a great deal. I went from unique function names to singletons to one aspect and now to two. The design changed a lot in the middle as well. I unpacked the parsing of data from being on the data driven site and moved that to the site running the plugin.

    The evolution of all this was for a simple reason. I wanted the JSON output to be generated as fast as possible, grabbed, and parsed locally. If the data takes less time to generate on my end, then the speed becomes more of a factor of how fast can the end-user’s site run. That would allow more people to use my plugin.

    A secondary bonus reason was that I hate repeating myself in code. If I only have one place to update my code that generates the list of dead characters, for example, then there are fewer odds I’ll screw up and only edit one of the six places it gets used.

    This means that the code I posted last week doesn’t look at all like that anymore.

    On My Site (aka The Service)

    In a file called bury-your-queers.php (yes, this is for that site) I have a class called LWTV_BYQ_JSON.

    In that class I have a constructor that calls the rest_api_init and that’s where I define my URLs. I already had the last-death set, so now I’ve added in two more for on-this-day:

    	public function rest_api_init() {
    		register_rest_route( 'lwtv/v1', '/last-death', array(
    			'methods' => 'GET',
    			'callback' => array( $this, 'last_death_rest_api_callback' ),
    		) );
    		register_rest_route( 'lwtv/v1', '/on-this-day/', array(
    			'methods' => 'GET',
    			'callback' => array( $this, 'on_this_day_rest_api_callback' ),
    		) );
    		register_rest_route( 'lwtv/v1', '/on-this-day/(?P<date>[\d]{2}-[\d]{2})', array(
    			'methods' => 'GET',
    			'callback' => array( $this, 'on_this_day_rest_api_callback' ),
    		) );
    	}
    

    The reason I have two for my new route is that I wanted both the main URL and the sub URL to work. That is /lwtv/v1/on-this-day/ and /lwtv/v1/on-this-day/03-03/ both work. They both call the same callback which checks what was passed to it. If the params for date are empty, it assumes today:

    	public function on_this_day_rest_api_callback( $data ) {
    		$params = $data->get_params();
    		$this_day = ( $params['date'] !== '' )? $params['date'] : 'today';
    		$response = $this->on_this_day( $this_day );
    		return $response;
    	}
    

    The callback grabs the function on_this_day(), passing the date through to it. Now this is the first BIG change. I pulled the code to generate the list of all the dead out of the function for last_death because it’s called twice. Now it calls LWTV_Loops::post_meta_query which is just a class for all my common loops that get reused a lot. They’re no faster than making the query the regular way, they’re just neater and tidier.

    	public static function on_this_day( $this_day = 'today' ) {
    
    		if ( $this_day == 'today' ) {
    			$this_day = date('m-d');
    		}
    
    		// Get all our dead queers
    		$dead_chars_loop  = LWTV_Loops::post_meta_query( 'post_type_characters', 'lezchars_death_year', '', 'EXISTS' );
    		$dead_chars_query = wp_list_pluck( $dead_chars_loop->posts, 'ID' );
    		$death_list_array = self::list_of_dead_characters( $dead_chars_query, $dead_chars_loop );
    
    		$died_today_array = array();
    
    		foreach ( $death_list_array as $the_dead ) {
    			if ( $this_day == date('m-d', $the_dead['died'] ) ) {
    				$died_today_array[ $the_dead['slug'] ] = array(
    					'slug' => $the_dead['slug'],
    					'name' => $the_dead['name'],
    					'url'  => $the_dead['url'],
    					'died' => date( 'Y', $the_dead['died'] ),
    				);
    			}
    		}
    
    		if ( empty( $died_today_array ) ) {
    			$died_today_array[ 'none' ] = array(
    				'slug' => 'none',
    				'name' => 'No One',
    				'url'  => site_url( '/cliche/dead/' ),
    				'died' => date('m-d'),
    			);
    		}
    
    		$return = $died_today_array;
    		return $return;
    	}
    

    Output

    And all that works to output this (if you pick 03-03):

    {"alisa-davies":{"slug":"alisa-davies","name":"Alisa Davies","url":"https:\/\/lezwatchtv.com\/character\/alisa-davies\/","died":"2010"},"lexa":{"slug":"lexa","name":"Lexa","url":"https:\/\/lezwatchtv.com\/character\/lexa\/","died":"2016"}}
    

    or this (if you pick a date where no one died):

    {"none":{"slug":"none","name":"No One","url":"https:\/\/lezwatchtv.com\/cliche\/dead\/","died":"02-19"}}
    

    Unlike what I did for ‘last death’, here I’m only reporting the year. The reason is that’s all I care about just now. I’m passing the date through, so I don’t need that information anymore.

    On Your Site (aka The Plugin)

    The plugin for this has three classes. The first is the master class to build out the widgets and shortcodes and also to parse the data. The other two are for the widgets.

    Parsing the data is what we’re going to talk about today.

    The function is straightforward. You pass the date to the function, it grabs the data for the date (defaulting to ‘today’ if none is provided) and spit out the resulting data:

    	public static function on_this_day( $this_day = 'today' ) {
    		$echo_day = ( $this_day == 'today' )? time() : strtotime( date('Y').'-'.$this_day );
    		$json_day = ( $this_day == 'today' )? '' : $this_day.'/' ;
    
    		$request  = wp_remote_get( 'https://lezwatchtv.com/wp-json/lwtv/v1/on-this-day/'.$json_day );
    		$response = wp_remote_retrieve_body( $request );
    		$response = json_decode($response, true);
    
    		$count = ( key($response) == 'none' )? 0 : count($response) ;
    		$how_many = __('no characters died!', 'bury-your-queers');
    		$the_dead = '';
    
    		if ( $count > 0 ) {
    			$how_many = sprintf( _n( '%s character died:', '%s queer female characters died:', $count, 'bury-your-queers' ), $count );
    
    			$the_dead = '<ul class="byq-otd">';
    			foreach ( $response as $dead_character ) {
    				$the_dead .= '<li><a href="'.$dead_character['url'].'">'.$dead_character['name'].'</a> - '.$dead_character['died'] .'</li>';
    			}
    			$the_dead .= '</ul>';
    		}
    
    		$onthisday = '<p>'. sprintf( __( 'On %s, %s', 'bury-your-queers'), date('F jS', $echo_day ), $how_many ).'</p>';
    		$return = $onthisday.$the_dead;
    
    		return $return;
    	}
    

    I picked paragraphs and un-ordered lists, since I feel those would be easily formatted by most people.

  • JSON Rest API (In Peace)

    JSON Rest API (In Peace)

    This week I’ve been talking about my list of dead characters, which I needed to order by year and wanted to display the most recent death in a widget.

    Part of my end goal with all this was a dream I had to let people have a widget on their own site where they could display the most recently dead character. There were other ideas I had, like a ‘this day in YEAR, Character X died.’ But for now, I wanted to start my delving into the JSON API with something more simple.

    Because this is my first serious go at it.

    Sketching Out The Concept

    To do this, I broke my concept down into the logical steps of what was needed.

    • Output the data
    • Create a JSON URL
    • Format the data there

    And no, I have no idea how to do any of that, except outputting the data.

    The Rest API

    To initialize the Rest API, you have to call a function on init() and that’s where it defines the URL that will be called. There are three (or four) parts to a URL:

    • Namespace
    • Version
    • Route
    • Arguments

    The version isn’t technically required, but in the interests of future proofing, it’s probably a good idea. And in this specific case, I don’t have any arguments I want to pass through. You’re going to get just the output of the last dead. In deciding that, I was able to determine the most sensible structure.

    My namespace should be for my site, not just this ‘show the dead’ feature. This is not always going to be the case, but since I’m adding in what I presume will be the first of some APIs, it’s wise to name in a way that is forward thinking. Similarly, I need my route to be logically named, and in this case I’m showing the last death, so I called it last-death.

    This makes my desired URL /wp-json/MYSITE/v1/last-death/ and the code is this:

    public function rest_api_init() {
    	register_rest_route( 'MYSITE/v1', '/last-death', array(
    		'methods' => 'GET',
    		'callback' => array( $this, 'rest_api_callback' ),
    	) );
    }
    

    The callback code is what gets my data, and based on my original widget resulted in the page displaying the following:

    "It has been <strong>2 months and 6 days<\/strong> since the last death: <a href=\"https:\/\/example.dev\/character\/gina\/\">Gina<\/a> - December 7, 2016"
    

    But I didn’t want it to be formatted like that. Instead, I wanted the code to spit out an array. To do that with my existing setup, I rewrote the dead_char() function, taking out all the parts that generated the days since the last death and instead put that in a separate plugin. Now this one gives an API output:

    {"name":"Gina","url":"https:\/\/example.dev\/character\/gina\/","died":1481068800,"since":"5792233"}
    

    That has the added bonus of letting anyone who wants to call it on their own for whatever they want isn’t stuck with my design. Yay, open source!

    The Code

    My JSON code went into a class like this:

    class MYSITE_Dead_Character_JSON {
    
    	/**
    	 * Constructor
    	 */
    	public function __construct() {
    		add_action( 'init', array( $this, 'init') );
    	}
    
    	/**
    	 * Init
    	 */
    	public function init() {
    		add_action( 'rest_api_init', array( $this, 'rest_api_init') );
    	}
    
    	/**
    	 * Rest API init
    	 *
    	 * Creates the callback - /MYSITE/v1/last-death/
    	 */
    	public function rest_api_init() {
    		register_rest_route( 'lwtv/v1', '/last-death', array(
    			'methods' => 'GET',
    			'callback' => array( $this, 'last_death_rest_api_callback' ),
    		) );
    	}
    
    	/**
    	 * Rest API Callback
    	 */
    	public function last_death_rest_api_callback( $data ) {
    		$response = $this->last_death();
    		return $response;
    	}
    
    	/**
    	 * Generate List of Dead
    	 *
    	 * @return array with last dead character data
    	 */
    	public static function last_death() {
    		// Get all our dead queers
    		$dead_chars_loop  = MYSITE_tax_query( 'post_type_characters' , 'cliches', 'slug', 'dead');
    		$dead_chars_query = wp_list_pluck( $dead_chars_loop->posts, 'ID' );
    
    		// List all queers and the year they died
    		if ( $dead_chars_loop->have_posts() ) {
    			$death_list_array = array();
    
    			// Loop through characters to build our list
    			foreach( $dead_chars_query as $dead_char ) {
    
    				// Date(s) character died
    				$died_date = get_post_meta( $dead_char, 'lezchars_death_year', true);
    				$died_date_array = array();
    
    				// For each death date, create an item in an array with the unix timestamp
    				foreach ( $died_date as $date ) {
    					$date_parse = date_parse_from_format( 'm/d/Y' , $date);
    					$died_date_array[] = mktime( $date_parse['hour'], $date_parse['minute'], $date_parse['second'], $date_parse['month'], $date_parse['day'], $date_parse['year'] );
    				}
    
    				// Grab the highest date (aka most recent)
    				$died = max( $died_date_array );
    
    				// Get the post slug
    				$post_slug = get_post_field( 'post_name', get_post( $dead_char ) );
    
    				// Add this character to the array
    				$death_list_array[$post_slug] = array(
    					'name' => get_the_title( $dead_char ),
    					'url' => get_the_permalink( $dead_char ),
    					'died' => $died,
    				);
    			}
    
    			// Reorder all the dead to sort by DoD
    			uasort($death_list_array, function($a, $b) {
    				return $a['died'] <=> $b['died'];
    			});
    		}
    
    		// Extract the last death
    		$last_death = array_slice($death_list_array, -1, 1, true);
    		$last_death = array_shift($last_death);
    
    		// Calculate the difference between then and now
    		$diff = abs( time() - $last_death['died'] );
    		$last_death['since'] = $diff;
    
    		$return = $last_death;
    
    		return $return;
    	}
    
    }
    new MYSITE_Dead_JSON();
    

    You may notice that I don’t seem to have a loop, and I call this instead:

    $dead_chars_loop  = MYSITE_tax_query( 'post_type_characters' , 'cliches', 'slug', 'dead');
    

    For various reasons, I reuse a lot of loop calls. To make my own theme and plugin more human readable, that function does the query. It looks like this:

    function MYSITE_tax_query( $post_type, $taxonomy, $field, $term, $operator = 'IN' ) {
    	$query = new WP_Query ( array(
    		'post_type'       => $post_type,
    		'posts_per_page'  => -1,
    		'no_found_rows'   => true,
    		'post_status'     => array( 'publish', 'draft' ),
    		'tax_query' => array( array(
    			'taxonomy' => $taxonomy,
    			'field'    => $field,
    			'terms'    => $term,
    			'operator' => $operator,
    		),),
    	) );
    	wp_reset_query();
    	return $query;
    }
    

    Since I have to do a lot of odd calls for the statistics on that site, it became smarter to do it that way.

    Calling the Data From YOUR Site!

    I made an endpoint! This is all well and good, but the new question is “How does someone else include this on their site?”

    The answer there is they need a widget. And it’s a widget I’ve mostly already made! All I had to do was create a plugin that made the widget and instead of calling the loops locally, just call the API.

    class Bury_Your_Dead {
    
    	public function __construct() {
    		add_action( 'widgets_init', array( $this, 'last_death_register_widget' ) );
    	}
    
    	public function last_death_register_widget() {
    		$this->widget = new BYD_Last_Death_Widget();
    		register_widget( $this->widget );
    	}
    
    	public static function last_death() {
    		$request  = wp_remote_get( 'https://example.dev/wp-json/MYSITE/v1/last-death/' );
    		$response = wp_remote_retrieve_body( $request );
    		$response = json_decode($response, true);
    
    		$diff = $response['since'];
    
    		$years = floor($diff / (365*60*60*24));
    		$months = floor(($diff - $years * 365*60*60*24) / (30*60*60*24));
    		$days = floor(($diff - $years * 365*60*60*24 - $months*30*60*60*24)/ (60*60*24));
    
    		$since = '';
    		if ( $years != 0 ) $since .= sprintf( _n( '%s year, ', '%s years, ', $years, 'MYSITE' ), $years );
    		if ( $months != 0 ) $since .= sprintf( _n( '%s month', '%s months', $months, 'MYSITE' ), $months );
    		$since .= ( $years != 0 )? ', ' : ' ';
    		$since .= ( $months != 0 )? __('and ', 'MYSITE') : '';
    		if ( $days != 0 ) $since .= sprintf( _n( '%s day', '%s days', $days, 'MYSITE' ), $days );
    
    		$response['since'] = $since;
    
    		return $response;
    	}
    }
    new Bury_Your_Dead();
    
    class BYD_Last_Death_Widget extends WP_Widget {
    
    	protected $defaults;
    
    	function __construct() {
    
    		$this->defaults = array(
    			'title'		=> __( 'The Most Recent Death', 'MYSITE' ),
    		);
    
    		$widget_ops = array(
    			'classname'   => 'dead-character deadwidget',
    			'description' => __( 'Displays time since the last WLW death', 'MYSITE' ),
    		);
    
    		$control_ops = array(
    			'id_base' => 'lezwatch-dead-char',
    		);
    
    		parent::__construct( 'lezwatch-dead-char', __( 'The Latest Dead', 'MYSITE' ), $widget_ops, $control_ops );
    	}
    
    	function widget( $args, $instance ) {
    
    		extract( $args );
    		$instance = wp_parse_args( (array) $instance, $this->defaults );
    
    		echo $args['before_widget'];
    
    		if ( ! empty( $instance['title'] ) ) {
    			echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'] ) . $args['after_title'];
    		}
    
    		$dead_character = Bury_Your_Dead::last_death();
    
    		echo sprintf( __('It has been %s since the last death', 'MYSITE'), '<strong>'.$dead_character['since'].'</strong>' );
    		echo ': <a href="'.$dead_character['url'].'">'.$dead_character['name'].'</a> - '.date('F j, Y', $dead_character['died'] );
    
    		echo $args['after_widget'];
    	}
    
    	function update( $new_instance, $old_instance ) {
    		$new_instance['title'] = strip_tags( $new_instance['title'] );
    		return $new_instance;
    	}
    
    	function form( $instance ) {
    		$instance = wp_parse_args( (array) $instance, $this->defaults );
    
    		?>
    		<p>
    			<label for="<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>"><?php _e( 'Title', 'MYSITE' ); ?>: </label>
    			<input type="text" id="<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'title' ) ); ?>" value="<?php echo esc_attr( $instance['title'] ); ?>" class="widefat" />
    		</p>
    		<?php
    	}
    }
    

    Whew. That’s huge, I know! And you may have noticed I snuck some translation in there. Always look forward!

  • REST API – Democratizing Reading

    REST API – Democratizing Reading

    Democratize Publishing.

    We say that a lot in WordPress. We boldly state that the goal of WordPress is to democratize publishing through Open Source, GPL software.

    I’d like to turn that on it’s ear for a moment.

    The purpose of the REST API is to democratize reading.

    Democratize Discovery

    One of the myths of websites is that if you build it, people will come. If that was true, we’d never need plugins like Yoast SEO and we’d never need to self-promote. The reality is that we have to work hard and make our content good. WordPress helps us make it look good, and makes it easier to get it out there, and usually the rest is up to us.

    There’s another aspect to discovery, though, and that is the ease of findability. We already address this in WordPress to a degree with RSS, but as much as I’d love to say that was that, it’s not. It’s 2017. People don’t want RSS, they want email and they want the information on social media immediately.

    And? They want apps on their phones that alert them to new data.

    Democratize Consuming

    Reading data with WordPress is easy. We go to a webpage, we see the data, we consume, we move on. With emails and social media, people usually have to click to come to your site and read. While this is good for your traffic, anytime a person has to click you’re running a risk they might not click. That’s why Tweetstorms are more consumable than blog posts. While they are far more transient, they’re accessible in an immediate way.

    Making the consuming of data more direct, a more one-to-one relationship, improves the chances that someone will actually read the information. Much of this can be achieved with a good lede, but readers are well to aware of click-bait today. “She tried this blogging software. You won’t believe what happened next!”

    Right. You get the point. In order to get people to read, you have to make it easier for them to read. Converting WordPress posts to something an app can read needs to be easier for the blogger, or they won’t be able to have success.

    Democratize Reading

    The REST API does just that.

    It makes the discovery and consumption of your website easier by simplifying your output.

    When you look at a website you see the design and the layout and the wonderful beauty. When an app reads your data, however, it doesn’t want or need any of that. An app needs the raw data. And the REST API does that. It outputs the data in a super basic and simple way. Furthermore, it lets you add on to this and output specific data in special ways.

    Democratize Publishing

    You can publish your data in multiple ways. Today, we all know about the blogging aspect of WordPress. But here are some other ways you could share your data:

    • Allow users to download a CSV with all the products on your site and their costs
    • Create a plugin that calls custom data, allowing others to have a widget with the data
    • Power a mobile app without loading your theme

    Could you do all that without the REST API? Of course.

    Does the REST API make it easier and thus help you democratize faster? Yes. It does.

    The REST API can change your life, if you’d only let it.

  • Using JSON with Hugo

    Using JSON with Hugo

    I know I’ve been talking about Hugo a lot, but the whole reason I say and wrapped my head around it was that I wanted to make a website using JSON.

    Making something out of the JSON API in WordPress isn’t easy, and I decided to start with something hard. I thought I would make a Multisite network to be the back end of my site, and then call the JSON API to generate the content.

    Why?

    It doesn’t make my site (much) faster, though it makes it more cacheable. Mostly what it does is lets me separate church and state. I can use WordPress to write content, and then call it however I want. That would be Hugo. If I build the site via Hugo locally, then every time I generate the files it can pull in the data on the fly.

    Enable the API

    This is easy. Install WordPress 4.4 and install v2 of the Rest API plugin. I also installed Jetpack for reasons of using Calypso.

    You absolutely have to use the Rest API plugin. WordPress 4.4 adds in some of the bits, but the API plugin gives you the actual endpoints. You’ll need these later.

    Call the API

    This was also easy. Kind of. Making a jquery file that called the content was fairly straightforward but… Making it responsive and reactive was hard.

    What I really wanted to do was have some web app, js powered without node, that just called the data and kept the url structure. And for that what I need is a JSON client.

    It was incredibly hard to find how to make a static HTML website powered by JSON. I’d see Rachel Baker’s presentation on making a WordPress theme with the JSON API but that wasn’t what I wanted to do. I mean, in a way it was. The theme itself was what I wanted, but I didn’t want to run it with WordPress.

    I did a lot of research and finally stumbled onto restful.js by marmelab. I read their blog post on the product and it looked like what I wanted. I needed something that would run without Node.js since I wanted to do this on Apache.

    Consuming a RESTful Web Service Dynamically

    And this is when I starting banging my head against a table. None of the solutions I’d found were working for me. Nothing. Rachel was right. I was in a bit over my head. Oh she was nice enough not to say it that way, but they way she looked at me was very Jewish Mom of her.

    In order to stop feeling useless, I decided to learn Hugo. It had come up a few times on my search for a dynamic static site. Hugo has LiveReload which, if you’re familiar with most static generators, is pretty cool. The idea is the pages rebuild as you edit the content (or theme) files.

    If you run hugo server locally on your laptop, you can see this today. Hugo upped the ante by tossing in the ability to run it on the server and the ability to watch the data files. It also has the ability to call JSON remotely.

    I feel it’s important to note that you cannot trigger that LiveReload when you’re using external URLs. But anytime you edit a file and LiveReload is triggered, Hugo will read the URL content from your cache. If you’ve disabled cache, it will download it fresh. Don’t disable cache unless you have an unlimited API. And no, I don’t know how long the cache is good for.

    Sadly, OAuth or other authentication methods are not working yet, but for now that’s okay because I’d been in over my head for so long, I stepped back.

    Understanding JSON First

    Okay fine. Once I realized I’d tried to do too much at first, I went back to that static filmography I had.

      {
      	"role": "actor",
        "title": "White Christmas",
        "slug": "white-christmas",
        "type": "Movie",
        "character": "Phil Davis",
        "notes": null,
        "dates": 1954
      }
    

    This is basic stuff. A simple chunk by chunk. And to call the file in a shortcode, I did this:

    {{ range $.Page.Site.Data.filmography }}
    	{{ if eq $role .role }}
    		<li>{{ .title }}: <strong>{{ .character }}</strong> </li>
    	{{ end }}
    {{ end }}
    

    Actually I did a lot more but you get the idea. And if you’re wondering about the if statement at the top, it’s so I can pass a parameter to my shortcode:

    {{< filmography role="actor" >}}

    It took me longer than I’d like to figure that out. At first I had multiple filmography files (actor, writer, producer) and I was trying to look through them all. In the end, I realized this simple JSON and a simple call was better.

    A Little More JSON

    There was another case, though. I had lists of episodes compiled into separate JSON files, one per show. This is logical and maintainable after all, but it meant I couldn’t use the same logic loop in the same way.

    What I really needed was to loop through $.Page.Site.Data.episodes.SHOWNAME in order to get the data from that show. And I couldn’t add on a variable to my range call.

    But as it happens, Hugo is clever and if I say {{ range $.Page.Site.Data.episodes }} it will give me the file episodes.json if that exists. But if there happens to be a folder called episodes then it will give me all the JSON files in there.

    I read through the data documentation on Hugo a few times to understand the hierarchy but it breaks down really logically:

    ├── data
    |   ├── episodes
    |   |   ├── continum.json
    |   |   └── fringe.json
    |   |   └── sense8.json
    |   ├── movies.json
    |   ├── musicals.html
    

    Data {dot} episodes {dot} continum

    And if I ran this:

    {{ range $.Page.Site.Data.episodes }}
    	<li>{{ .show }}<li>
    {{ end }}
    

    Then I got this:

    • continum
    • fringe
    • sense8

    I already knew I could do a range within a range, and finally I came up with this:

    {{ $show := $.Page.Params.show }}
    
    {{ range $.Page.Site.Data.episodes }}
    	{{ if eq .show $show }}
    		<li>{{ .title }}</li>
    	{{ end }}
    {{ end}}
    

    The shortcode checks the post it’s on and, if the Front Matter has ‘show’ defined, it will give me a list of all titles (episode titles) for that show.

    I added in an extra check for the season parameter. This one is passed through the shortcode:

    {{< episodelist season="1" >}}

    And that, in turn is called in the shortcode above the output for title:

    {{ range where .episodes "season" "==" $season }}

    So nothing will display unless the show in the JSON file matches the show on the page with the shortcode, and the season matches the one defined in the shortcode.

    Now I actually have a more robust check. If no season is defined, it shows all episodes (useful for one-season shows, right?). But you get the idea.

    How Did This Help?

    Remember my JSON example before? Here’s what it looks like for Fringe:

    {
    "show" : "fringe",
    "episodes": [
      {
        "epnum": "1",
        "season": "1",
        "title": "Pilot",
        "slug": "pilot",
        "airdate": "2008-09-08T22:00:00.000Z",
        "rating": "5",
        "summary": "Walter gets a cow named Gene to experiment on ethically."
      },
      ...
    ]}
    

    Instead of just started with those naked chunks, I have a definition of the show name (fringe – lowercase because I want to compare it to other lowercase things and I’m lazy) and the definition of a section for episodes. That’s the whole reason why that call for seasons works the way I want it to.

    This helped me to understand and visualize JSON. By taking a simple JSON list (the filmography) I learned the basics of connecting code and content. Then by taking the more complex scenario, where I needed nested data, I understood that relationship.

    The next step will be making a simple WordPress site and calling the JSON remotely. Obviously I have to figure out how to trick it into making fake permalinks, but baby steps. Baby steps.