In the last two posts, we've taken a brief survey of the wp_remote_get function as well as a practical implementation of how to use it.

Before moving on to other aspects of the WordPress HTTP API, it's important to know exactly what information is returned from a remote call using wp_remote_get so that you're able to have a full understanding of the data that's returned, to write more defensive code, and to write more complicated requests should the need arise.

So in this final article on performing GET requests, we're going to review exactly that.

A Review of the Request

Remember that whenever you make a request using wp_remote_get, you don't only have to specify a URL. Additionally, you can also send an optional array of arguments, each of which can cause the server to response differently if it's looking for particular information.

The Arguments

In many cases, the arguments won't be needed as the default values will suffice; however, if you're working with an advanced API or are looking for a full understanding of the arguments, then the following information should explain what each of the available arguments are, how to use them, and the impact that it has on the request being made.

Method

This argument refers to the type of request that's being made. The thing is, since we're using wp_remote_get, we're obviously explicitly making a GET request.

That said, the argument will accept, GET, POST, and HEAD. If you're opting to use the latest version of the HTTP protocol, then you may also specify OPTIONS, PUT, DELETE, CONNECT, and TRACE.

These particular methods are beyond the scope of this particular article since we're primarily focusing on GET requests, but I wanted to mention them all here for completeness.

Timeout

This argument is how long the request should wait before giving up on waiting for a response. The value is specified in seconds and the default value is five.

So, practically speaking, you're saying that "initiate a request and wait five seconds for a response. If no response is received, return an error."

Though I've never had a problem with the default value, this may be something worth changing if you happen to be working with a server that's busy, and/or that only handles a low number of requests per second.

Redirection

Similar to the timeout argument, this value specifies how long the request should wait for a redirection before giving up.

The thing is, GET requests will rarely result in a redirect. More often than not, GET requests will attempt to connect to a URL to retrieve data (and it may or not send data in the query string), and then will simply handle the response or the error once the request has completed or timed out.

If, however, you plan on implementing any type of redirection mechanism, then this value can be specified in seconds. And, like the timeout argument, the default value is five seconds.

HTTPVersion

This refers to the version of the HTTP protocol that's being used. Though the technical aspects of this are beyond the scope of this series, each version of the protocol supports a varying number of a request type.

We covered each of these above and because we're explicitly making GET requests with the use of wp_remote_get, then this value isn't one we'd need to modify.

However, for completeness, at the time of this writing, the HTTP protocol currently has version 1.0 and 1.1. Depending on what version of the protocol your server supports, you may be able to use a wider variety of methods.

Blocking

This argument refers to the ability to make a request without actually holding up the loading of a page or waiting for a request to complete.

By default, this value is set to true as in the context of GET requests, we want to wait for the response to return so that we can do something with it; however, if you're fine making a request (though this is typically done with a POST request) for which you don't care about a response, then you can set this value to false.

Headers

This argument includes anything that you want to be sent across the wire other than the default values. When performing a GET request, I personally have yet to find a reason to use anything other than what is sent by default; however, that doesn't mean you won't need to send something more specialized in the future.

Headers generally consist of information such as the content type, the encoding of the content, the MIME type, and so on.

These particular values are beyond the scope of this article; however, I'm planning to revisit them when we talk about general remote requests. The point in mentioning them here is simply to define exactly what's possible given this article.

Body

This argument is simple and for anyone who has done any work with response data knows that this is basically the content of the request that's being sent.

In the context of a GET request, this may or may not consist of any values. Often times, GET requests include query string parameters which can serve as content for the request; however, if you need to specify more information than key/value pairs or need an explicit place to state your content, then this is the argument in which you'd do so.

Cookies

Finally, if there are any cookies that you need to send along with your request, then this is the parameter in which you'd specify them.

This is obviously most useful within the context of requesting data from a URL with which you've established some sort of session or in which some information currently resides on the client machine - as a cookie, of course - and that is likely necessary to send across the wire to the server.

As with many of the arguments above, this is something that isn't frequently used in a GET request, but is still open for specification, nonetheless.

Conclusion

Based on what we've seen so far, this article may make wp_remote_get look exceptionally more complicated than our practical example. The thing is, it doesn't have to be that way!

Remember, the information shared here is purely to demonstrate what you can use while working with this particular API method - not what you have to use.

As we continue to look at the HTTP API, we'll be seeing these particular arguments more and more; however, they are used differently - and oftentimes more frequently - than with other methods. Still, it's worth covering them here as they are part of the accepted parameters of wp_remote_get.