Default Endpoints

In the previous section, you hit two different REST API endpoints: users and posts. WordPress, by default, has several endpoints available for retrieving all types of data.

• Posts: /wp/v2/posts/
• Post Revisions: /wp/v2/posts/<id>/revisions/
• Pages: /wp/v2/pages/
• Page Revisions: /wp/v2/pages/<id>/revisions/
• Categories: /wp/v2/categories/
• Tags: /wp/v2/tags/
• Comments: /wp/v2/comments/
• Taxonomies: /wp/v2/taxonomies/
• Media: /wp/v2/media/
• Users: /wp/v2/users/
• Post Types: /wp/v2/types/
• Post Statuses: /wp/v2/statuses/
• Settings: /wp/v2/settings/
• Themes: /wp/v2/themes/
• Search: /wp/v2/search/
• Blocks: /wp/v2/blocks/
• Block Revisions: /wp/v2/blocks/<id>/autosaves/
• Block Renderer: /wp/v2/block‐renderer/

It's easy to see how much data is available by default from the WordPress REST API.

REST API Clients

When working with an API, whether it be the WordPress REST API or another source, it can be helpful to use a REST API client to verify the request calls and data results quickly. This can help you quickly confirm the API endpoints, that authentication is working as needed, and that the data returned is what you expect. The following sections discuss two popular REST API clients.

Postman

Postman is a popular collaboration platform for API development. Currently, Postman has apps available for Mac, Windows, or Linux systems. A proprietary option, with premium features, Postman has a good free version that supports the basics that you'll need to validate, authenticate, and test against an API. To view all features and download it, visit https://www.getpostman.com.

Both Insomnia and Postman give you an intuitive UI to interact with any available API. As an example, let's use a simple GET request to return post ID 1, which is most likely the Hello World example post created when you installed WordPress. First open the Insomnia app on your computer. If this is your first time running Insomnia, you will be prompted to either create a new request or import one from a file, so click New Request. Enter a name for your new request environment like Localhost Testing and click the Create button. Now enter the WordPress REST API request URL and click Send. In this example, the request URL will be as follows:

http://localhost/prowp/wp-json/wp/v2/posts/1

The results returned for post ID 1 are displayed in the Preview tab, as shown in Figure 12‐3.

As you can see, using a REST API client tool can quickly help you validate the data you are working with. Once you have perfected your API requests, you can begin integrating those requests into your custom WordPress plugins.

Try using a REST API client to request data from the default WordPress API endpoints you reviewed in the “Default Endpoints” section earlier in this chapter.

Authentication

All data that is public in WordPress can be accessed via the REST API and does not require authentication. For example, a published post on your website is public and therefore available to retrieve using the REST API. Draft posts are not public, because they are not published yet, so you will need to authenticate with WordPress to retrieve that information.

Let's look at an example accessing draft post data from the command line using SSH. If you are using macOS or Linux, you can use SSH from the terminal without any special software. On Windows, you'll need to install an SSH client like Putty (https://www.putty.org).

On a Mac, open your Terminal application and enter the following command, replacing localhost with the WordPress website you want to access:

curl -X GET http://localhost/wp-json/wp/v2/posts

This command will return a set of published posts from your local website. Now let's try retrieving draft posts.

http://localhost/wp-json/wp/v2/posts?status=draft

You'll notice that an error message is returned: Status is forbidden. This is because you have not authenticated with WordPress, so draft posts are not available. As a basic example of authentication, you'll use the Basic Authentication handler plugin for WordPress: https://github.com/WP-API/Basic-Auth. This plugin does exactly what it says: it uses basic authentication to send your username and password with every request. This is a basic form of authentication and should only be used for testing, as there are other, more secure methods available for production websites.

Once you have installed and activated the plugin, you can now pass your credentials through the request to access draft blog posts like so:

curl -X GET --user username:password -i http://localhost/wp-json/wp/v2/
posts?status=draft

Simply replace username and password with your WordPress username and password to properly authenticate your account within the request. WordPress will now return your draft posts.

Now let's look at the same example using the Insomnia REST API client you reviewed in the previous section. Using a GET request without authentication, you will receive a Status is forbidden 400 error message, shown in Figure 12‐4.

To authenticate, simply click the Auth tab and select Basic Auth. Enter your username and password and send the request again. This time the request is authenticated, and the results are returned and displayed, as shown in in Figure 12‐5.

As you can see, this is a basic example demonstrating how to authenticate with WordPress to retrieve nonpublic data using the WordPress REST API. Later in this chapter we'll cover accessing REST API data within a custom plugin utilizing the HTTP API.

Enhanced Authentication

As shown in the previous example, basic authentication allows you to access data not publicly available from the WordPress REST API. The downside to this method is that the auth credentials are sent in plain text with every request, so as you would expect, this is not very secure. Let's look at some enhanced authentication options available when accessing the REST API.

• Application Passwords: Authenticate users by generating a unique password for each application without revealing the user's main account password. Application passwords can be revoked for each application individually.
  • https://wordpress.org/plugins/application-passwords
• JWT (JSON Web Tokens) Authentication: JSON Web Tokens are an open standard (RFC 7519) that defines a compact and self‐contained way for securely transmitting information between two systems as a JSON object.
  • https://wordpress.org/plugins/jwt-authentication-for-wp-rest-api
• OAuth 1.0a Server: Use the OAuth 1.0a protocol to allow delegated authorization allowing applications to access the REST API using a set of secondary credentials.
  • https://wordpress.org/plugins/rest-api-oauth1
• REST API Authentication: A more robust option is the REST API Authentication plugin from miniOrange. This plugin supports multiple authentication options including basic auth, key authentication, JWT authentication, and OAuth 2.0. The plugin is freely available on WordPress.org. A premium version, with enhanced features and professional support, is also available.
  • https://wordpress.org/plugins/wp-rest-api-authentication

Custom Endpoints

As with almost everything in WordPress, the REST API can be extended, making it easy to return any custom data you might need. To do this, you will register a custom endpoint for the REST API. These custom endpoints can return any type of dataset you require.

Let's create a custom endpoint that returns the first post title for a specific author in WordPress. First let's construct a custom function to return the exact data you are looking for.

/**
 * Grab latest post title by the author ID
 *
 * @param array $data Options for the function.
 * @return string|null Post title for the latest, * or null if none.
 */
function pdev_return_post_title_by_author_id( $data ) {
 
    $posts = get_posts( array(
        'author' => absint( $data['id'] ),
    ) );
 
    if ( empty( $posts ) ) {
        return new WP_Error( 'no_author', 'Invalid author', array( 'status' =>
        404 ) );
    }
 
    return $posts[0]->post_title;
 
}

As you can see, you create a custom function called pdev_return_post_title_by_author_id(), which accepts a $data parameter. You'll use the get_posts() function to query the posts within WordPress. You are passing in the author ID value via the $args parameter to return posts for a given author only. For security reasons, you wrap the author ID value in absint() to confirm that only an integer is passed through the function. If the $posts variable is empty, meaning get_posts() returned no results, you'll set a custom WP_Error notice to alert the system that no posts matched with the author ID provided. Finally, you'll return the post title if a match is found.

Now that your function is in place to return the results, let's create a custom REST API endpoint to return the results. To do so, you'll utilize the register_rest_route() function, which accepts the following parameters:

• $namespace: A URL segment unique to your plugin.
• $route: The base URL for the route being added.
• $args: Optional array of options for your endpoint.
• $override: If the route already exists, should we override it?

If your namespace is pdev‐plugin/v1 and your route is / author, then the URL for it will be /wp‐json/pdev‐plugin/v1/author/.

Now let's register the custom endpoint for the example. You'll see the namespace, route, and an array of $args to define the method and callback function to use, as shown in the following code:

add_action( 'rest_api_init', 'pdev_custom_endpoint' );
 
// Register your REST API custom endpoint
function pdev_custom_endpoint() {
 
    register_rest_route( 'pdev-plugin/v1', '/author/(?P<id>d+)', 
        array(
            'methods'  => 'GET',
            'callback' => 'pdev_return_post_title_by_author_id',
        ) 
    );
 
}

Now you have a custom REST API endpoint located here:

http://localhost/prowp/wp-json/pdev-plugin/v1/author/<ID>

where <ID> is the author ID whose post you want to retrieve. As a test, let's send a GET request to the new endpoint. In this example, you want to find the latest post from Jason Voorhees, who is user ID 3 in WordPress. In this example, the post titled “My Time at Crystal Lake” is returned, since that is the latest post published by Jason. You can see the results when you access the new custom endpoint, as shown in Figure 12‐6.

Let's review the full REST API custom endpoint plugin, shown here:

<?php
/*
Plugin Name: PDEV REST API Custom Endpoint
Plugin URI: https://example.com/
Description: Register a custom endpoint in the WP REST API
Author: WROX
Author URI: http://wrox.com
*/
 
/**
 * Grab latest post title by the author ID
 *
 * @param array $data Options for the function.
 * @return string|null Post title for the latest, * or null if none.
 */
function pdev_return_post_title_by_author_id( $data ) {
 
    $posts = get_posts( array(
        'author' => absint( $data['id'] ),
    ) );
 
    if ( empty( $posts ) ) {
        return new WP_Error( 'no_author', 'Invalid author', array( 'status' =>
        404 ) );
    }
 
    return $posts[0]->post_title;
 
}
 
add_action( 'rest_api_init', 'pdev_custom_endpoint' );
 
// Register your REST API custom endpoint
function pdev_custom_endpoint() {
 
    register_rest_route( 'pdev-plugin/v1', '/author/(?P<id>d+)', 
        array(
            'methods'  => 'GET',
            'callback' => 'pdev_return_post_title_by_author_id',
        ) 
    );
 
}

What Is an HTTP Request?

Hyper Text Transfer Protocol (HTTP) is the networking protocol that is no less than the foundation of data communication for the World Wide Web.

GET /file.html HTTP/1.1
Host: www.example.com
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0) Firefox/3.6
Referer: https://www.google.com/search?q=example.com
Cookie: lastvisit=235456684

HTTP/1.1 200 OK
Date: Mon, 31 October 2020 22:38:34 GMT
Server: Apache/1.3.3.7 (Unix) (Red-Hat/Linux)
Last-Modified: Sun, 30 Oct 2020 23:11:55 GMT
Set-Cookie: lastvisit=235456951
Content-Length: 438
Content-Type: text/html; charset=UTF-8

How to Make HTTP Requests in PHP

In basic PHP, without WordPress that is, there are several common ways to send HTTP requests. It is interesting to know the basics because you sometimes need to code a portion of code in a non‐WordPress environment.

The following examples all do the same thing: send a GET request to https://wordpress.org and display the content received (that is, their index page).

<?php
        
$r = new HttpRequest( 'https://wordpress.org/', HttpRequest::METH_GET );
$r->send () ;
echo $r->getResponseBody();
?>

<?php
        
if( $stream = fopen( 'https://wordpress.org/', 'r' ) ) {
    echo stream_get_contents( $stream );
    fclose( $stream );
}
?>

<?php
        
$handle = fopen( 'https://wordpress.org/', 'r' );
$contents = '';
while( !feof( $handle ) ) {
    $contents .= fread( $handle, 8192 );
}
fclose( $handle );
echo $contents;
?>

<?php
        
$fp = fsockopen( 'www.example.com', 80, $errno, $errstr, 30 );
if ( !$fp ) {
    echo “$errstr ($errno)<br/>
”;
} else {
    $out = “GET / HTTP/1.1
”;
    $out .= “Host: www.example.com
”;
    $out .= “Connection: Close

”;
    fwrite( $fp, $out );
    while ( !feof( $fp ) ) {
        echo fgets( $fp, 128 );
    }
    fclose( $fp );
}
?>

<?php
        
$ch = curl_init();
        
curl_setopt( $ch, CURLOPT_URL, 'https://wordpress.org/' );
curl_setopt( $ch, CURLOPT_HEADER, 0 );
curl_exec( $ch );
curl_close( $ch );
?>

The wp_remote_ Functions

You can execute an HTTP request within WordPress mostly using functions wp_remote_get(), wp_remote_post(), and wp_remote_head(), obviously for GET, POST, and HEAD requests.

These functions all operate the same way.

• The HTTP request is performed using the eponymous method.
• They accept two parameters, one required and one optional.
• They return an array or an object.

The syntax of these three functions follows:

<?php
        
$get_result  = wp_remote_get( $url, $args );
$post_result = wp_remote_post( $url, $args );
$head_result = wp_remote_head( $url, $args );
        
?>

These three functions can be considered as simple shortcuts to the more generic wp_remote_request(). Indeed, the three preceding lines are equivalent to the three following ones:

<?php
        
$get_result  = wp_remote_request( $url, array( 'method' => 'GET' ) );
$post_result = wp_remote_request( $url, array( 'method' => 'POST' ) );
$head_result = wp_remote_request( $url, array( 'method' => 'HEAD' ) );
        
?>

The function wp_remote_request() works the same way as the other wp_remote_* functions, so everything that follows applies to any wp_remote_ function.

You'll now learn what parameters they need and what data they return, and then you'll play with them.

<?php
 
$defaults = array (
    'method' => 'GET',
    'timeout' => 5,
    'redirection' => 5,
    'httpversion' => '1.0',
    'user-agent' => 'WordPress/5.3; https://example.com/',
    'reject_unsafe_urls' => $url,
    'blocking' => true,
    'headers' => array (),
    'cookies' => array (),
    'body' => NULL,
    'compress' => false,
    'decompress' => true,
    'sslverify' => true,
    'sslcertificates' => ABSPATH . WPINC . '/certificates/ca-bundle.crt',
    'stream' => false,
    'filename' => NULL,
    'limit_response_size' => NULL
)     
?>

<?php
        
$args = array(
    ‘user-agent’ => ‘Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:72.0)
    Gecko/20100101 Firefox/72.0’,
);
        
$result = wp_remote_get( $url, $args );
        
?>

// Register a custom page for your plugin
add_action( 'admin_menu', 'pdev_create_menu' );
             
function pdev_create_menu() {
             
    // Create custom top-level menu
    add_menu_page( 'PDEV Movies Page', 'PDEV Movies',
        'manage_options', 'pdev-movies', 'pdev_movie_api_results',
        'dashicons-smiley', 99 );
             
}

// Request and display Movie API data
function pdev_movie_api_results() {
 
// Set your API URL
$request = wp_remote_get( 'https://sampleapis.com/movies/api/horror' );

// If an error is returned, return false to end the request
if( is_wp_error( $request ) ) {
    return false;
}

// Retrieve only the body from the raw response
$body = wp_remote_retrieve_body( $request );
 
// Decode the JSON string
$data = json_decode( $body );

// Verify the $data variable is not empty
if( ! empty( $data ) ) {
    
    echo '<ul>';
 
    // Loop through the returned dataset 
    foreach( $data as $movies ) {
 
        echo '<li>';
            echo '<a href="https://www.imdb.com/title/' . 
            esc_attr( $movies->imdb_id ) . '">';
            echo '<img src="' . esc_url( $movies->poster_url ) .
            '" height="75"><br/>';
            echo esc_html( $movies->title );
            echo '</a>';
        echo '</li>';
 
    }
 
    echo '</ul>';
}

<?php
/*
Plugin Name: Horror Movie API Example Plugin
Plugin URI: https://example.com/
Description: Example using the HTTP API to parse JSON from a remote
horror movie API
Author: WROX
Author URI: http://wrox.com
*/
 
// Register a custom page for your plugin
add_action( 'admin_menu', 'pdev_create_menu' );
             
function pdev_create_menu() {
             
    // Create custom top-level menu
    add_menu_page( 'PDEV Movies Page', 'PDEV Movies',
        'manage_options', 'pdev-movies', 'pdev_movie_api_results',
        'dashicons-smiley', 99 );
             
}
 
// Request and display Movie API data
function pdev_movie_api_results() {
 
    // Set your API URL
    $request = wp_remote_get( 'https://sampleapis.com/movies/api/horror' );
 
    // If an error is returned, return false to end the request
    if( is_wp_error( $request ) ) {
        return false;
    }
 
    // Retrieve only the body from the raw response
    $body = wp_remote_retrieve_body( $request );
 
    // Decode the JSON string
    $data = json_decode( $body );
 
    // Verify the $data variable is not empty
    if( ! empty( $data ) ) {
        
        echo '<ul>';
 
        // Loop through the returned dataset 
        foreach( $data as $movies ) {
 
            echo '<li>';
                echo '<a href="https://www.imdb.com/title/' .
                esc_attr( $movies->imdb_id ) . '">';
                echo '<img src="' . esc_url( $movies->poster_url ) .
                '" height="75"><br/>';
                echo esc_html( $movies->title );
                echo '</a>';
            echo '</li>';
 
        }
 
        echo '</ul>';
    }
 
}

<?php
        
var_dump( wp_remote_get( 'malformed-url' ) );
        
?>

object(WP_Error)#1212 (2) {
  ["errors"]=>
  array(1) {
    ["http_request_failed"]=>
    array(1) {
      [0]=>
      string(29) "A valid URL was not provided."
    }
  }
  ["error_data"]=>
  array(0) {
  }
}

<?php
$bad_urls = array(
   'malformed',
   'irc://example.com/',
   'http://inexistant',
);
        
foreach( $bad_urls as $bad_url ) {
 
    $response = wp_remote_head( $bad_url, array( 'timeout' => 1 ) );
 
    if( is_wp_error( $response ) ) {
 
        $error = $response->get_error_message();
        echo "<p>Trying $bad_url returned: <br/> $error </p>";
 
    }
    
}
        
?>

Trying malformed returned:
A valid URL was not provided.
 
Trying irc://example.com/ returned:
A valid URL was not provided.
 
Trying http://inexistant returned:
cURL error 6: Couldn't resolve host 'inexistant'

<?php
 
var_dump( wp_remote_get( 'http://example.com/asdfgh' ) );
 
?>

array(4) {
        
  [“headers”] => array(5) {
     [“date”] => string(29) “Thu, 16 Jan 2020 20:04:01 GMT”
     [“server”] => string(85) “Apache/2.4.41 mod_ssl/2.2.8 PHP/7.3”
     [“content-length”] => string(3) “648”
     [“connection”] => string(5) “close”
     [“content-type”] => string(25) “text/html; charset=utf-8”
  }
        
  [“body”]=> string(1256) “<html><head>
<title>404 Not Found</title>
</head><body>
(... snip ...)
</body></html>
“
        
  [“response”] => array(2) {
     [“code”] => int(404)
     [“message”] => string(9) “Not Found”
  }
        
  [“cookies”] => array(0) {}
}

<?php
        
$url = 'https://www.example.com/bleh';
        
// Send GET request
$response = wp_remote_get( $url );
        
// Check for server response
if( is_wp_error( $response ) ) {
        
    $code = $response->get_error_message();
    wp_die( 'Requests could not execute. Error was: ' . $code );
        
}
        
// Check that the server sent a “404 Not Found” HTTP status code
if( wp_remote_retrieve_response_code( $response ) == 404 ) {
        
    wp_die( 'Web page not found' );
        
}
        
// So far, so good
echo 'Web page found!';
        
?>

Advanced Configuration and Tips

Thanks to these wp_remote_ functions, you are now able to perform most tasks involving HTTP requests in a standard WordPress environment. But not all environments are customary, and not all tasks are basic. Fortunately, the HTTP API is extensible and versatile.

For instance, it is frequent that networks in corporate environments are isolated behind a firewall or a proxy. You will now read how to bypass this and maybe treat HTTP responses differently.

In the following sections, you will also learn how to fine‐tune the behavior of the HTTP API, utilizing its hooks and filters, for example to log requests for troubleshooting.

<?php
 
define( 'WP_PROXY_HOST', 'firewall.corp.example.com' );
define( 'WP_PROXY_PORT', '3128' );
define( 'WP_PROXY_USERNAME', 'username' );
define( 'WP_PROXY_PASSWORD', 'password' );
 
?>

<?php
 
// these hosts will not go through the proxy
define( 'WP_PROXY_BYPASS_HOSTS', 'sales.example.com, hr.example.com' );
 
?>

<?php
        
// block all requests through the HTTP API
define( 'WP_HTTP_BLOCK_EXTERNAL', true );
        
// except for these hosts
define( 'WP_ACCESSIBLE_HOSTS',
    'api.wordpress.org, sales.example.com, partner.web' );
?>

<?php
        
// Hook into the filter that sets user agent for HTTP requests
add_filter( 'http_headers_useragent', 'pdev_plugin_user_agent' );
        
// Set your own user agent
function pdev_plugin_user_agent() {
    global $wp_version;
        
    return "WordPress version $wp_version ; ".
           "Need a WordPress specialist? Contact us! ".
           "PDEV Studios www.example.com";
           
}
        
?>

<?php
        
// before the request is sent, you will find:
$parsed_args = apply_filters( 'http_request_args', $parsed_args, $url );
        
// once the response is processed, you will read:
return apply_filters( 'http_response', $response, $parsed_args, $url );
 
?>

<?php
/*
Plugin Name: PDEV Log HTTP requests
Plugin URI: https://example.com/
Description: Log all HTTP requests into a flat text file for further analysis
Author: WROX
Author URI: http://wrox.com
*/
        
// Hook into filters
add_filter( 'http_request_args', 'pdev_http_log_request', 10, 2 );
add_filter( 'http_response', 'pdev_http_log_response', 10, 3 );
        
// Log requests.
// Parameters passed: request parameters and URL
function pdev_http_log_request( $r, $url ) {
        
    // Get request parameters formatted for display
    $params = print_r( $r, true );
        
    // Get date with format 2010-11-25 @ 13:37:00
    $date = date( 'Y-m-d @ H:i:s' );
        
    // Message to log:
    $log = <<<LOG
    $date: request sent to $url
    Parameters: $params
    --------------
        
LOG;
        
    // Log message into flat file
    error_log( $log, 3, dirname( __FILE__ ).'/http.log' );
        
    // Don't forget to return the requests arguments!
    return $r;
}
        
// Log responses
// Parameters passed: server response, requests parameters and URL
function pdev_http_log_response( $response, $r, $url ) {
        
    // Get server response formatted for display
    $resp = print_r( $response, true );
        
    // Get date with format 2020-10-31 @ 13:37:00
    $date = date( 'Y-m-d @ H:i:s' );
        
    // Message to log:
    $log = <<<LOG
    $date: response received from $url
    Response: $resp
    --------------
        
LOG;
        
    // Log message into flat file
    error_log( $log, 3, dirname( __FILE__ ).'/http.log' );
        
    // Don't forget to return the response!
    return $response;
        
}
        
?>

Create

Let's look at an example that creates a new post on an external WordPress website using the REST API. First, let's register a basic menu page in the Dashboard.

// Register a custom page for your plugin
add_action( 'admin_menu', 'pdev_create_menu' );
             
function pdev_create_menu() {
             
    // Create custom top-level menu
    add_menu_page( 'PDEV REST API FUN', 'PDEV REST API',
        'manage_options', 'pdev-rest-api', 'pdev_create_new_post',
        'dashicons-smiley' );
             
}

Now you have an area to work with your code. Next, let's create a simple form that when submitted will trigger the request to create a new post.

<h1>Create a Post using the REST API</h1>
<p>Click the button below to create a new post on an external WordPress
website using the REST API</p>
<form method="post">
    <input type="submit" name="submit" class="button-primary" 
    value="Create Post"/>
</form>

As you can see, there is nothing special here, just a simple HTML form. Now comes the fun part, defining the data you intend to send to the REST API for your new post, as shown here:

if ( isset( $_POST['submit'] ) ) {
 
    // Set the API URL to send the request
    $api_url = 'http://example.com/wp-json/wp/v2/posts';
 
    // Using Basic Auth, set your username and password
    $api_header_args = array(
            'Authorization' => 'Basic ' . base64_encode( 'brad:pa55w0rd' )
         );
 
    // Create the new post data array
    $api_body_args = array(
         'title'   => 'REST API Test Post',
         'status'  => 'draft',
         'content' => 'This is my test post. There are many like it, but this
         one is mine.',
         'excerpt' => 'Read this amazing post'
         );

First you check whether the form submit button has been posted, using the isset() PHP function, and if the form has been submitted, we know it's time to create the new post. Next, you'll create variables to hold the new post information. The first variable is $api_url, which contains the URL to the API of the WordPress website you plan to create your new post on. This needs to be a different website from the one running the plugin you are creating.

Next, you'll define the $api_header_args array, which sends the basic auth credentials to the REST API. Remember, for basic auth to work, the website you are creating the new post on needs to be running the Basic Auth plugin located at https://github.com/WP-API/Basic-Auth. Simply replace the USERNAME and PASSWORD text with a real username and password to authenticate.

Finally, you'll create the $api_body_args array, which contains all of the data for your new post. In this example, you set the title, content, and excerpt fields. You are also setting the post to a draft status so it is not published publicly yet.

Now that all the request data has been set, it's time to fire off the request to the remote REST API. You'll use the wp_remote_post() HTTP API function to do this. You'll notice you are passing in the three variables you set previously: $api_url, $api_header_args, and $api_body_args.

// Send the request to the remote REST API
$api_response = wp_remote_post( $api_url, array(
     'headers' => $api_header_args,
     'body' => $api_body_args
) );
         
// Decode the body response
$body = json_decode( $api_response['body'] );
 
// Verify the response message was 'created' 
if( wp_remote_retrieve_response_message( $api_response ) === 'Created' ) {
     echo '<div class="notice notice-success is-dismissible">';
     echo '<p>The post ' . $body->title->rendered . ' has been created
          successfully</p>';
     echo '</div>';
}

Once the request has been sent, you'll use json_decode() to decode the body response from the API. Using the wp_remote_retrieve_response_message() function, you can quickly check whether the response message is Created, which means the post was successfully created, and show a success message. That's it! You have just successfully created a new post on a remote WordPress website using the REST API!

Update

Now that you have created a new post using the REST API, let's send a request to update the post. To do this, you'll use much of the same code as before, with a few minor adjustments.

// Set the API URL to send the request
$api_url = 'http://example.com/wp-json/wp/v2/posts/<ID>';
 
// Using Basic Auth, set your username and password
$api_header_args = array(
        'Authorization' => 'Basic ' . base64_encode( USERNAME:PASSWORD' )
    );
 
// Create the post data array to update
$api_body_args = array(
    'title'   => 'UPDATED: REST API Test Post'
    );
 
// Send the request to the remote REST API
$api_response = wp_remote_post( $api_url, array(
    'headers' => $api_header_args,
    'body' => $api_body_args
) );
         
// Decode the body response
$body = json_decode( $api_response['body'] );
 
// Verify the response message was 'created' 
if( wp_remote_retrieve_response_message( $api_response ) === 'OK' ) {
    echo '<div class="notice notice-success is-dismissible">';
    echo '<p>The post ' . $body->title->rendered . ' has been updated 
         successfully</p>';
    echo '</div>';
}

First the $api_url needs to be updated to include the unique post ID you want to update. Simply replace <ID> with the post ID in the previous code sample. You'll pass the same basic auth credentials in your $api_header_args array. The $api_body_args array will include any data you want to update. In this example, you are going to update the post title, so set that to something different from the original.

Next, you'll send the request and decode the body response just as before. The final change is to verify the response message is OK, meaning the post was updated. That's it! When executing the code, the post ID defined in the request will receive an updated title.

Delete

You have successfully created and updated a post. The final step is to delete a post using the REST API.

// Set the API URL to send the request
$api_url = 'http://example.com/wp-json/wp/v2/posts/<ID>/';
 
// Using Basic Auth, set your username and password
$api_header_args = array(
        'Authorization' => 'Basic ' . base64_encode( 'USERNAME:PASSWORD' )
    );
 
// Send the request to the remote REST API
$api_response = wp_remote_post( $api_url, array(
    'method'  => 'DELETE',
    'headers' => $api_header_args
) );
         
// Decode the body response
$body = json_decode( $api_response['body'] );
 
// Verify the response message was 'created' 
if( wp_remote_retrieve_response_message( $api_response ) === 'OK' ) {
 
    echo '<div class="notice notice-success is-dismissible">';
    echo '<p>The post ' . $body->title->rendered . ' has been deleted 
        successfully</p>';
    echo '</div>';
 
}

The $api_url will match the update request, which requires a post ID to be set. You'll notice you are setting the method to DELETE in the wp_remote_post() call. This is what tells the REST API to delete the post based on the ID in the $api_url. The code will not successfully trash the post when executed.

Now let's review the entire plugin to create, update, and delete a post using the WordPress REST API. Remember to update the $api_url variable as well as the USERNAME and PASSWORD fields for basic auth to work.

<?php
/*
Plugin Name: REST API - Create, Update, and Delete Post Examples
Plugin URI: https://example.com/
Description: Create, update, and delete a new post using the WordPress REST API
Author: WROX
Author URI: http://wrox.com
*/
 
// Register a custom page for your plugin
add_action( 'admin_menu', 'pdev_create_menu' );
             
function pdev_create_menu() {
             
    // Create custom top-level menu
    add_menu_page( 'PDEV REST API FUN', 'PDEV REST API',
        'manage_options', 'pdev-rest-api', 'pdev_create_new_post',
        'dashicons-smiley' );
             
}
 
function pdev_create_new_post() {
 
    if ( isset( $_POST['create-post'] ) ) {
       
        // Set the API URL to send the request
        $api_url = 'http://example.com/wp-json/wp/v2/posts';
 
        // Using Basic Auth, set your username and password
        $api_header_args = array(
                'Authorization' => 'Basic ' . base64_encode( 'USERNAME:PASSWORD' )
            );
 
        // Create the new post data array
        $api_body_args = array(
            'title'   => 'REST API Test Post',
            'status'  => 'draft',
            'content' => 'This is my test post. There are many like it, but this
                          one is mine.',
            'excerpt' => 'Read this amazing post'
            );
 
        // Send the request to the remote REST API
        $api_response = wp_remote_post( $api_url, array(
            'headers' => $api_header_args,
            'body' => $api_body_args
        ) );
         
        // Decode the body response
        $body = json_decode( $api_response['body'] );
 
        // Verify the response message was 'created' 
        if( wp_remote_retrieve_response_message( $api_response ) === 'Created' ) {
            echo '<div class="notice notice-success is-dismissible">';
            echo '<p>The post ' . $body->title->rendered . ' has been created
                 successfully</p>';
            echo '</div>';
        }
 
    }elseif ( isset( $_POST['update-post'] ) ) {
 
        // Set the API URL to send the request
        $api_url = 'http://example.com/wp-json/wp/v2/posts/<ID>/';
 
        // Using Basic Auth, set your username and password
        $api_header_args = array(
                'Authorization' => 'Basic ' . base64_encode( 'USERNAME:PASSWORD' )
            );
 
        // Create the post data array to update
        $api_body_args = array(
            'title'   => 'UPDATED: REST API Test Post'
            );
 
        // Send the request to the remote REST API
        $api_response = wp_remote_post( $api_url, array(
            'headers' => $api_header_args,
            'body' => $api_body_args
        ) );
         
        // Decode the body response
        $body = json_decode( $api_response['body'] );
        
        // Verify the response message was 'created' 
        if( wp_remote_retrieve_response_message( $api_response ) === 'OK' ) {
            echo '<div class="notice notice-success is-dismissible">';
            echo '<p>The post ' . $body->title->rendered . ' has been updated 
                 successfully</p>';
            echo '</div>';
        }
 
    }elseif ( isset( $_POST['delete-post'] ) ) {
 
        // Set the API URL to send the request
        $api_url = 'http://example.com/wp-json/wp/v2/posts/<ID>/';
 
        // Using Basic Auth, set your username and password
        $api_header_args = array(
                'Authorization' => 'Basic ' . base64_encode( 'USERNAME:PASSWORD' )
            );
 
        // Send the request to the remote REST API
        $api_response = wp_remote_post( $api_url, array(
            'method'  => 'DELETE',
            'headers' => $api_header_args
        ) );
         
        // Decode the body response
        $body = json_decode( $api_response['body'] );
 
        // Verify the response message was 'created' 
        if( wp_remote_retrieve_response_message( $api_response ) === 'OK' ) {
 
            echo '<div class="notice notice-success is-dismissible">';
            echo '<p>The post ' . $body->title->rendered . ' has been deleted
                 successfully</p>';
            echo '</div>';
 
        }
 
    }
    ?>
    <h1>Create or Update a Post using the REST API</h1>
    <p>Click the button below to create a new post on an external WordPress
       website using the REST API</p>
    <form method="post">
        <input type="submit" name="create-post" class="button-primary"
               value="Create Post"/>
        <input type="submit" name="update-post" class="button-primary"
               value="Update Post"/>
        <input type="submit" name="delete-post" class="button-primary"
               value="Delete Post"/>
    </form>
    <?php
 
}

Resources

There are some great resources available for working with the REST and HTTP APIs. When looking for online help, it's important to look for newer articles and tutorials. Older examples, even from a year ago, could be using out‐of‐date methods.

The following are some resources to help you grow your knowledge on the APIs covered in this chapter:

• REST API Handbook: Official WordPress project handbook
  • https://developer.wordpress.org/rest-api
• HTTP API Handbook: Official WordPress project handbook
  • https://developer.wordpress.org/plugins/http-api
• Kinsta Blog: Extensive overview of the WordPress REST and HTTP API
  • https://kinsta.com/blog/wordpress-rest-api
  • https://kinsta.com/blog/wordpress-http-api