Working with the WordPress HTTP API

working with wordpress http apis

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!


Key Takeaways:

  • The WordPress HTTP API simplifies making remote HTTP requests: requests for information that return (and may also alter) webpage content using HyperText Transfer Protocol (HTTP), the fundamental means of communication on the internet.
  • The wp_remote_get(), wp_remote_post(), and wp_remote_head() functions make GET, POST, and HEAD requests, respectively. wp_remote_request() can make all forms of HTTP requests.
  • The HTTP responses received as the result of HTTP requests are further processed by response handler functions. Prewritten handler functions, such as wp_remote_retrieve_body() and wp_remote_retrieve_header(), greatly simplify parsing many responses.

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.

Understanding HTTP

The web works through HTTP: HyperText Transfer Protocol. HTTP is a “protocol,” an established style, of requests and responses between computers. It’s how two computers “shake hands” and transfer data between each other.

What do they transfer? They transfer “HyperText,” meaning HTML. (Remember, HTML stands for “HyperText Markup Language.”)

So HTTP is an agreed-upon standard by which HTML gets sent back and forth between computers. Since HTML moving between computers is pretty much what the web is, HTTP is absolutey essential to its functioning.

HTTP Methods: GET, HEAD, and POST

Different HTTP methods are used for different goals.

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

GET is probably the most common and familiar HTTP method. GET requests are how you retrieve an HTTP resource, including its main body. Every time your browser visits a webpage like https://wpshout.com, it’s actually sending a GET request to the website’s server.

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

HEAD

HEAD is a GET request, where you don’t want the actual body of the resource. If you were just collecting metadata about websites, for example, you could just make a HEAD request to https://wpshout.com and you’d get an answer like you would for a GET, but without the body that holds all the actual content. (You’d just learn, for example, what character encoding scheme WPShout uses. A thorough list is in the HTTP specifications at: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.)

POST

To create an HTTP request with “side effects”—make the server save data to the database, for example—the most common method is the POST request. A GET request is a simple “Can I have that?” A POST is more elaborate: “I’m providing a certain amount of information for you to do something with (such as save to a database), and after I’ve done that I’d like information in return.” If you fill out a form, post a new tweet, or check-in at a location, some layer of software somewhere is probably making a POST request for you.

The WordPress HTTP API

The WordPress HTTP API provides simple PHP functions for making HTTP requests and handling the resulting HTTP responses.

The WordPress HTTP API offers a few simple and “WordPress-y” PHP functions that allow you to make HTTP requests, and handle the corresponding responses. These functions are of two types:

  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.

HTTP Requesting Functions

The requesting functions let you make GET, POST, and HEAD requests (as well as requests for less common HTTP methods). They’re named consistently:

  • 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 );.

An Example: Creating a GET Request

To GET the homepage of WPShout, you can use wp_remote_get():

/* 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 );

Or you can use wp_remote_request() to do exactly the same thing:

/* 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.

Handling the HTTP Response with Helper Functions

What you get back from the wp_remote_request() family of functions is an HTTP response, passed back as a structured PHP array.

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

Partial List of Helper Functions

These functions all take the HTTP response itself as their first (and, for all but wp_remote_retrieve_header(), only) argument. This response is the result of the HTTP requesting function, which we saved as the variable $response in the code examples above.

  • 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!

Why Not Use PHP’s Default Methods to Make HTTP Requests?

PHP has a number of ways to make HTTP requests. Why use WordPress’s? As usual, the answer is that doing things “the WordPress way” has benefits. WordPress has seen, gotten bug reports from, and been battle-tested against a massive number of servers, hosting configurations, and meddling hosts. The WordPress functions are set to have workarounds and fallbacks for many of these contingencies. As a WordPress developer, it’s good to take advantage of that accumulated “it-works-anywhere” flexibility.

What We’ve Learned

We hope this has given you a sound sense of what the WordPress HTTP API is for and how to use it. You can use this API to get anything from WPShout’s homepage to a JSON payload from Twitter—the sky’s the limit.

Summary Limerick

To talk to remote sites, please try
The HTTP API:
For parsing request
And response, it’s the best,
And its functions are easy as pie.

Quiz Time!

  1. A remote HTTP request would be the right solution for:
    1. A “recent posts” plugin
    2. A “recent Facebook posts” plugin
    3. A “blog aggregator” plugin targeting other WordPress sites
  2. The following HTTP request is good for causing state changes, such as writing to a database:
    1. GET
    2. HEAD
    3. POST
  3. Of the following response handler functions, this one requires a second argument:
    1. wp_remote_retrieve_header()
    2. wp_remote_retrieve_headers()
    3. wp_remote_retrieve_body()

Answers and Explanations

  1. B. A is not “remote,” and C would probably be best handled using an RSS feed reader.
  2. C. GET and HEAD should simply retrieve information without changing state.
  3. A. The second argument is the desired header, such as 'host'.

4 Comments
Most Voted
Newest Oldest
Inline Feedbacks
View all comments
Jenson
April 3, 2020 8:42 pm

Hi there

Thanks for this amazing post!

Is it possible to use these functions inside a separate project?

Example if I have a current Laravel written site and would like to post certain things to a WordPress site.

Would I need to add the “wp-includes” folder and use the functions?

This sounds like the work would need to be done within the wordpress side of things.

Thanks
Jenson

This Week in WordPress: WordCamp Europe and Core Dev Announcements | Silk Pixel Web
February 6, 2015 1:05 am

[…] Working with HTTP APIs in WordPress (WPShout). […]

This Week in WordPress: WordCamp Europe and Core Dev Announcements | Blue Digital Web Services
February 5, 2015 8:46 am

[…] Working with HTTP APIs in WordPress (WPShout). […]

This Week in WordPress: WordCamp Europe and Core Dev Announcements - WPMU DEV
February 5, 2015 7:42 am

[…] Working with HTTP APIs in WordPress (WPShout). […]