WordPress HTTP API

Why you should want to know about the WordPress HTTP API? Well, some WordPress installs may have CURL installed for instance, others may not. On some installs you’re allowed to do file_get_contents to external URLs, on others you’re not. If you’re relying on these features to work, your plugin might not work for a lot of users. That’s where the WordPress HTTP API comes in. It allows you to either GET or POST something from or to other sites outside of your WordPress site.

The WordPress HTTP API makes fetching from or posting to remote servers a breeze. It does this by allowing you to be transport agnostic when you fetch or post something. The HTTP API will choose the fastest and most reliable method out of the five different transports available in PHP. It’ll take care of discovering what transports are allowed on that server at that time.

The two most important functions and the ones you will probably use 99% of the time are:

wp_remote_get()

As the Codex explains, this is a wrapper function for the WordPress HTTP API that does a remote get call for you. In most cases you’ll only need to do:

$resp = wp_remote_get( 'http://example.com/' );

The body of the page that you requested can then be accessed through $resp['body']. You should actually check though whether the $resp['response']['code'] was actually 200 first, so do something like this:

if ( 200 == $resp['response']['code'] ) {
	$body = $resp['body'];
	// perform action with the content.
}

There’s also a function that can do this for you, although I don’t really like the way it works myself. This function is called wp_remote_retrieve_body. The code for it is as follows:

function wp_remote_retrieve_body( &$response ) {
	if ( is_wp_error($response) || ! isset($response['body']) )
		return '';

	return $response['body'];
}

You could use it in the following way:

$body = wp_remote_retrieve_body( wp_remote_get( 'http://example.com/' ) );

If something went wrong, $body would then be empty, so you’d have to check for that. Note that if the response code was 404, body could now contain the 404 page, as wp_remote_get, as far as I know, will not return an error when the result was a 404.

wp_remote_post()

If you want to post some data to a remote URL using the WordPress HTTP API, do the following:

$args = array(
	'body' => 'some data',
	'user-agent' => 'Yoast Coolness'
);
$resp = wp_remote_post( 'http://example.com', $args );

You can then handle $resp in the same way as with wp_remote_get. Both functions are actually wrapper functions on top of the function request in class WP_Http, see the XRef for that function for more details.

Yoast.com runs on the Genesis Framework

Genesis theme frameworkThe Genesis Framework empowers you to quickly and easily build incredible websites with WordPress. Whether you're a novice or advanced developer, Genesis provides you with the secure and search-engine-optimized foundation that takes WordPress to places you never thought it could go.

Read our Genesis review or get Genesis now!

13 Responses

  1. David ArtissBy David Artiss on 13 April, 2011

    Thanks for this.

    Using the HTTP API was one of the things you mentioned during your review of my plugin – I went hunting immediately to find out what was required and had already implemented it by the time you published this.

    None-the-less, learning more about the techniques you refer to in your reviews will be a real benefit.

    Suggestion – when you write a review and mention, say, using the HTTP API, why not provide a link to the appropriate post (such as this)?

    • Joost de ValkBy Joost de Valk on 13 April, 2011

      I’m actually working on connecting those two right now indeed ;)

  2. GeorgeBy George on 13 April, 2011

    HTTP API really is great. Unfortunately many plugin developers use cURL

    Joost why don’t you like wp_remote_retrieve_body?

    • Joost de ValkBy Joost de Valk on 13 April, 2011

      Because it’ll also return the body of a request that 404′d, and I typically don’t want that in my plugins.

  3. SanderBy Sander on 14 April, 2011

    Thanks for this great article Joost! Just what I needed for a plugin I’m working on :).

    I’ll subscribe to your newsletter so I won’t miss a thing..

    Greets, Sander

  4. JatinBy Jatin on 16 April, 2011

    Great Article. I agree with George that many developers still use cURL.

    Joost, I am really impressed with the way you handle every minor detail to make your plugins ‘almost perfect’ (I am saying this with reference to your reply to George). I am fan of your coding style.

    • Dave DoolinBy Dave Doolin on 16 April, 2011

      Jatin, I agree, Joost is a first stop for me when I need code examples. I have a massive localhost installation with probably 60 plugins I use for reference, very handy.

  5. DannyBy Danny on 17 April, 2011

    Great, wish I figured this one out before I wrote my own version of it. Switched to the WP API in my plugins now though. :-)

    Thanks Joost, hard to find and not exactly documented in the Codex yet!

  6. SebastianBy Sebastian on 2 May, 2011

    It’s kinda unrelated but: is there a way to retrieve the image size with the HTTP API or something similar. I do not wanna use an php-function, which requires f_open.

  7. Daniel TanBy Daniel Tan on 27 July, 2011

    Joost, thanks, great tips.

    Sebastian,
    to retrieve remote object size you could use
    wp_remote_head() function call. Then analyze raw response to parse out “Content-Length:” HTTP header.

  8. Thomas ClausenBy Thomas Clausen on 19 August, 2012

    Hi Joost

    I’ve been playing around with the same functions and ended up checking the response from wp_remote_get() the following way:

    $response = wp_remote_get( 'http://www.yourdomain.com/something/' );
    if ( is_wp_error( $response ) || 200 != wp_remote_retrieve_response_code( $response ) )
    return false;
    $result = wp_remote_retrieve_body( $response );

    Using the wp_remote_retrieve_response_code (http://codex.wordpress.org/Function_API/wp_remote_retrieve_response_code) you can make sure the response code isn’t 404.

    Thanks for some great posts and plugins.

  9. NathanBy Nathan on 24 December, 2012

    Hi all,

    I also agree that using WP functions is (or at least should be) a better solution.

    BUT, here is a problem:

    I am developing a plugin for a local payment gateway for a major WP shopping cart. I need to POST a few {key => value} pairs and receive a response with two authorisation parameters.

    Now comes the happy part: if I use wp_remote_post and provide it with a variable containing the url and an array variable containing the parameters – I get an error. Cracked my head, couldn\’t solve it. Now, if I use curl, with the same url variable and the same parameters array – works beautifully.

    Any ideas?

  10. ChrisBy Chris on 4 April, 2013

    I keep running into this theme of Article, but what I am in fact searching for is how to post to my self hosted blog, via the HTTP API, or Atom etc. I am attempting to write a simple app to post to my self hosted blog, and given I only need one picture and one price per post, I am hoping to avoid (and fairly certain I should be able to) a giant programming nightmare. Could you put me in the right direction?