A Look at the WordPress HTTP API: A Brief Survey of wp_remote_get

When it comes to making remote requests within the context of web sites, web applications, and even WordPress-based projects, the model that we follow is generally the same:

  • Initiate a request on the server-side
  • Handle the response when it's retrieved either by reading the response or catching the error
  • Return the response to the caller

This particular format is the same that's used in both synchronous and asynchronous (or Ajax-based) functionality. The thing is, if you're building a standard web application using PHP, Rails, Java, .NET, or any other platform, then they each have their own ways of doing it.

The same is true of WordPress; however, if you're working with WordPress, you're also working with PHP which means that you may be leveraging PHP functions rather than specific WordPress API's.

In this four part series, we're going to take a look at what it means to make a remote GET request, and in the second part, we're going to take a look at a practical approach to doing so.

Then in the last two articles, we're going to look at the arguments that wp_remote_get accepts as well as what you can accept from a response from the server when a request is completed. Ultimately, we should have a full understanding of this method's API as well as how to write quality and defensive code when implementing it in our projects.

But first, let's take a survey of what it even means to make a request.


What Is a Remote Request?

Simply defined, a remote request is when one server makes a request to another server. This can take several forms - sometimes it sends data, sometimes it's simply polling to see if the server is available, and sometimes it's requesting data.

In this particular series of articles, we're going to look at what it means to request data from another server. But first, here's how you can conceptually model one server talking to another, making a request, and then handling the data:

Remote Requests

Easy enough to understand, right?

For the advanced developers who are reading this, you know that there can be some advanced topics to cover here - perhaps authentication needs to occur (such as the use of keys and/or tokens), and you know that the response won't always be as clear cut as what is defined - but the truth is that if you look at the process from an abstract point of view, this is what you end up seeing.


How Are Requests Made in PHP?

This varies from application to application, but as mentioned earlier in this article we're primarily focused on PHP and WordPress and so the way that requests are typically made within PHP are using one of two functions:

  • file_get_contents
  • curl

Both of them can be used for remote requests, but one is a bit more flexible than the other.

file_get_contents

Essentially, file_get_contents accepts a string - basically a URL - and will return the data that's requested (or false on a failure).

This is arguably the most common way that novice developers will make remote requests. Truth be told, I used to do this a lot - and still do, depending on the requirements of the web application - but that's a topic for another series.

The details about file_get_contents can be read in the PHP manual. Though we're going to be taking a look at the WordPress-way of making remote requests, I recommend checking out this particular API just to be familiar with what it offers.

cURL

cURL - often written curl - is short for the "client URL library." Just like the name mentions, this is an entire library - versus a function - that provides developers a full set of features for making remote requests.

In addition to simply requesting data from a third-party URL, you're able to set parameters such as:

  • How to handle error numbers
  • Get information about a specific transfer
  • Initiate, perform, or close a session
  • Wait for activity on a specific connection
  • ...and more

Obviously, there's a lot to learn and a lot going on with this particular library.

Personally, if you're an advanced developer, I'm a fan of using cURL within the context of PHP-based web applications for the robust level of control that it offers.

If you're not familiar with this library, I highly recommend reading up on it in the PHP manual.


How Are Requests Made in WordPress?

Of course, as mentioned throughout the article, file_get_contents and cURL are important to know in PHP and are often used within the context of WordPress projects; however, there is a preferred function to use within WordPress.

Remember, just as we've looked at the WordPress Coding Standards to understand how to best write WordPress-based code, we also need to look at the APIs available to us to make sure that we're doing things the way that WordPress recommends.

So when it comes to making GET requests for WordPress, the function that we have available to us is wp_remote_get.

The function accepts two arguments:

  • The URL to which the request is being made
  • The array of arguments to send along with the request

The array of arguments are a bit beyond the scope of this particular article; however, the associated Codex article provides a quick read for exactly what we can send along with our request.

Some examples include:

  • How long before timing out
  • The version of the HTTP protocol to use
  • Headers
  • Cookies
  • ...and more

Finally, the function will request an entire array of data once the response has been sent. For example:

  • The headers from the server to which the request was made
  • The content type of the response
  • The actual response
  • ...and more.

We'll be talking more about the response in the third article in this series.

Obviously, the function is easiest enough to understand but it's really powerful. For those who are curious, part of the WordPress HTTP API (which this function is a part of) uses the cURL library internally.


Let's Make a Request

That said, initiating a request with wp_remote_get is really easy. In fact, we're going to be doing just that in the next article in the series.

Specifically, we're going to look at just how it easy it is to communicate with Twitter, receive data, and then display it in the browser. The nice thing is that we won't even have to use any OAuth authentication or any other libraries.

We'll use wp_remote_get, handle the response appropriately, and then display the information on the screen.

Tags:

Comments

Related Articles