This article explains how to use WordPress’s HTTP API, a set of PHP functions from within WordPress’s function library, to make remote HTTP requests to external resources, such as JSON REST APIs.

We use the WordPress HTTP API when we want to access remote resources—resources not present on the WordPress site we’re working from—which could be anything you can imagine, from data we access through Facebook’s or Twitter’s APIs to weather information published by government agencies. We make these remote requests using WordPress’s HTTP API functions, especially wp_remote_get(), wp_remote_post(), and wp_remote_head().

We’re proud to bring this article to you as a sample chapter from our full “learn WordPress development” guide Up and Running, now in its revised and expanded 3rd Edition.

If you like this chapter, check out Up and Running. There’s about 40 more chapters where this one came from. It’s the best guide to WordPress development out there.

Serious About Learning WordPress Development?

Get Up and Running Today

Up and Running is our complete “learn WordPress development” course. Now in its updated and expanded Third Edition, it’s helped hundreds of happy buyers learn WordPress development the fast, smart, and thorough way.

 

“I think anyone interested in learning WordPress development NEEDS this course.

Before I purchased Up and Running, I had taught myself some WordPress code, but lacked direction. Watching the course’s videos was like a bunch of lights being turned on.

I went from being vaguely familiar with how themes, functions and WordPress itself worked to mastering these. Everything became much clearer.

I very happily recommend this course to anyone willing to listen.”

–Jason Robie, WordPress developer

Take the next step in your WordPress development journey!

Get Up and Running Now

From time to time, you’ll need to call remote resources—resources on sites other than your own. A common way to do this is by making HTTP requests for the information you need. This chapter explains HTTP, and digs into WordPress’s HTTP API.

To be comfortable with HTTP APIs, you’ll need to understand a little bit about HTTP itself—first and foremost, that there are different methods of HTTP, and they’re used for different purposes. HTTP has eight methods in total, but to work with the WordPress HTTP API, we really only need to know three: GET, HEAD, and POST.

GET requests generally only retrieve information—the server shouldn’t create, change, or destroy information in the process of serving a GET request.

1. Requesting functions: Functions that make HTTP requests
2. Response handlers: Functions that help you to make sense of the responses you get back

In practice, you’ll use the requesting functions first, and then you’ll pass the returned results to the response handlers.

• wp_remote_get() is for GET requests
• wp_remote_post() is for POST requests
• wp_remote_head() is for HEAD requests

The first three functions are slightly specialized uses of a fourth function, wp_remote_request(), which itself can make every kind of HTTP request.

All four of these functions take the same two arguments:

1. A URL
2. An associative array of optional parameters

So they look like this: function_name( $url, $args );.

/* Environment: We're in a theme's functions.php, or a plugin file */

$args = array( 
	'timeout' => 10
);
$response = wp_remote_get( 'https://wpshout.com', $args );

/* Environment: We're in a theme's functions.php, or a plugin file */

$args = array( 
	'method' => 'GET',
	'timeout' => 10
);
$response = wp_remote_request( 'https://wpshout.com', $args );

Both code examples do precisely the same thing: they make an HTTP GET request for the WPShout homepage, and save the resulting HTTP response to the variable $response.

To show you the workings of $args, we’ve specified one optional parameter: timeout. This parameter takes an integer, and lets you specify how long, in seconds, you want to wait for the response before the request simply returns an error. So both examples above will wait 10 seconds before timing out, rather than the default of 5.

The $args array can take a number of other parameters, such as the following:

• 'redirect' takes an integer, and lets you specify how many, if any, redirects you’ll accept.
• 'blocking' takes a boolean, and dictates whether or not you want everything else in your script’s execution to wait on your request.
• 'sslverify' takes a boolean, and dictates whether to deny the response if the site’s SSL security certificate isn’t valid.

The full argument list is in the Codex, at: http://codex.wordpress.org/HTTP_API#Other_Arguments.

You can commonly use WordPress helper functions to find what you want in this response array, without needing to remember its full structure.

• wp_remote_retrieve_body: Gives you the actual body of the response. In the case of the request we made above to https://wpshout.com, you’d get all the HTML that the browser uses to render that page.
• wp_remote_retrieve_header requires a second function parameter: the name of the HTTP header you want from the response, such as 'host' or 'authorization'.
• wp_remote_retrieve_headers: Note the final “s”; this returns a PHP array of all the HTTP Headers contained in the response.
• wp_remote_retrieve_response_code: Will give you the numeric HTTP status code for the response—like 404 or 200 or 501. If the request succeeded, it’ll generally be in the 200s; if you did something wrong, it’ll be in the 400s; and if the server’s messing up it should be in the 500s.
• wp_remote_retrieve_response_message is useful if you find the numbers daunting. It’ll translate that number into a text version, like “Unauthorized” instead of 401.

An Example: Getting a Page’s Content with wp_remote_retrieve_body()

This example picks up where our use of wp_remote_get() above left off: we’ve got the results of a GET request made to https://wpshout.com. We’re going to leave that code in the example below to show you how everything fits together.

The example does something silly but functional: count how many times the word “WordPress” appears in the full HTML code of the WPShout homepage. If you paste the function below into a plugin file or functions.php, and then call the function itself with echo count_wordpress_on_wpshout_homepage();, your browser will display a number (54, the last time we checked).

/* Environment: We're in a theme's functions.php, or a plugin file */

// Counts how many times the HTML of the WPShout homepage includes the word "WordPress"
function count_wordpress_on_wpshout_homepage() {
	$args = array( 
		'timeout' => 10
	);
	$response = wp_remote_get( 'https://wpshout.com', $args );

	// Check for error
	if ( is_wp_error( $response ) ) {
		return;
	}

	// Parse remote HTML file
	$wpshout_homepage_html = wp_remote_retrieve_body( $response );

	// Check for error
	if ( is_wp_error( $wpshout_homepage_html ) ) {
		return;
	}

	// Count instances of "WordPress" in the page's HTML
	$count = substr_count( $wpshout_homepage_html, 'WordPress' );

	return $count;
}

Notes on This Example

It’s unlikely you’ll need to count uses of “WordPress” on many sites, but the HTTP methods we profiled here are very helpful for analyzing the contents of other websites. Aside from “web-scraper”-like uses that trend toward being semi-shady, these HTTP methods are most useful in the set of cases we’ll start to explore next chapter: working with the HTTP APIs—formal ways of exposing site data—offered by services like Facebook, Twitter, and the Oxford English Dictionary… and by other WordPress sites!