New Post has been published on Mocco
New Post has been published on http://mocco.sk/a-look-at-the-wordpress-http-api-a-brief-survey-of-wp_remote_post/
A Look at the WordPress HTTP API: A Brief Survey of wp_remote_post
In the first series on the WordPress HTTP API, we took a look at wp_remote_get. Specifically, we took a look at the following aspects of the API:
A survey of the function
A practical example thereof
How to handle the response
And understanding the arguments for the function
We’re going to continue the series on the WordPress HTTP API, but we’re going to turn our attention to a second method of the API: wp_remote_post.
Throughout the next set of articles, we’re going to take a survey of the function to understand what the function offers and why it’s useful, a practical example of how to implement it into our work, as well as how to understand the functions and the response that comes from the function.
With that said, let’s begin our survey of the function.
Remote Requests: A Refresh
If you’ve not been following along thus far, I highly recommend checking out the very first post in the series to at least understand the basics of how GET requests work.
Honestly, POST requests aren’t all that different. Just as GET requests are typically used to retrieve information from the server, POST requests are usually meant to send messages to the server.
But here’s the thing: both protocols are capable of sending data and receiving data, but here’s a general rule of thumb for how I typically approach GET and POST requests.
GET requests are typically used to retrieve information from the server, thus a response is expected
POST requests are typically used to send information to the server, and although a response may not be expected, it’s always nice to know if the server received and processed the response properly or not
Throughout the rest of the articles in this part of the series, we’ll be taking a look at how to handle both cases – that is, how to handle when no response is given and how to handle when a response is given.
A Summary of How Requests Are Made
Now, as far as requests are concerned at the server-level – specifically in PHP – they usually are made given the following two functions (unless you’re using a third-party library which is out of the scope of this series).
Though we’ve covered these in greater detail in the first post, I’ll be summarizing them here.
file_get_contents accepts a URL as a parameter and will return the data that’s requested or a false on failure. It’s a relatively common way to retrieve data for remote requests.
cURL is an entire library (rather than function) that provides full configuration options for developers to tweak to suit their needs. There’s much to learn about this library. If you’re an advanced developer, definitely check out cURL.
For the most part, understanding how requests are made is easy enough, but the degree to which you tweak how the requests are made is completely contingent on which option you opt to use – that is, file_get_contents or cURL.
Of course, this is more of the PHP-way of performing requests and although we may be implementing this in some of our work depending on the nature of the project, this does not necessarily cover the WordPress-way of doing it.
In fact, the above is a short refresher based on previous content. Nonetheless, it’s important to understand where we’re coming from, what’s available, and where we’re headed.
How POST Requests Are Made in WordPress
As mentioned, the notes above are far more closely related to PHP, so let’s a take a look at POST requests within the context of WordPress.
And if you’re in the business of building projects for WordPress or products on top of WordPress, it’s important to understand the APIs that are available to make sure that you don’t lose some type of feature or functionality with an upgrade to the core WordPress Application.
So, just as we’ve looked at the WordPress Coding Standards to review the best practices for writing WordPress-based code, we’re now going to be looking at the APIs available for writing POST requests using best practices.
To that end, enter wp_remote_post.
The function accepts two arguments:
The URL to which the request will be made
An array of arguments that help to tailor the request to the server.
Though the array of arguments are going to be somewhat outside of the scope of what we’re going to be doing in this series, it’s important to understand what’s available especially if you’re going to be doing more advanced work in the future:
method refers to which method is being used for the request. We’re obviously using POST given the nature of our API method.
timeout is how long you are willing to wait for the request to process before giving up. The default value is five seconds, but this can be decreased or increased based on the nature of your application.
redirection sounds like it’s the URL to which you’d be redirected after the request has completed, right? Instead, it’s a unit of time – in seconds – to wait on a redirection before giving up on the request.
user-agent allows us to control the user-agent that’s being sent along with the request. Usually, this is WordPress and the version number, but it’s obviously customizable.
blocking in short, if this is set to true then the script will continue to execute until something is returned from the server; otherwise, the script will continue operating without holding up the rest of your application. Granted, this comes at the expense of potentially never getting back a response, but depending on the conditions for which you’re building, this may be fine.
compress was introduced in WordPress 2.6 and allows you to send the body of the request in a compressed format. This will be outside the scope of our future articles.
decompress is similar to compress except that it’s on our end – if compressed data is received, this will allow us to decompress the content before doing any further work or processing on it.
sslverify was introduced in WordPress 2.8 and is useful for scenarios in which you need to check if an SSL certification is valid. If it’s not, then the request is denied; otherwise, you’re good to go. This option will also be outside the scope of this set of articles.
Obviously, there’s a lot of stuff that’s available. Over the next few articles, I hope to examine some of these in more detail, but first let’s take a look at a very simple, practical example of using the API function.
Let’s POST a Request
At this point, things should be clear enough, right? Using wp_remote_post should be just as easy as using wp_remote_get so starting in the next article, we’re going to be doing just that.
Until then, make sure you’ve reviewed all of the articles leading up to this point, and please leave any comments and/or questions to this particular post in the comments.
Next up, we’ll get to work!
Other parts in this series:A Look at the WordPress HTTP API: wp_remote_get – the Arguments
Check out the original source here.
