WordPress HTTP API: A Developer’s Guide

The WordPress HTTP API consists of a number of functions that help developers make HTTP calls more easily. No more messing with file_get_contents or cURL; instead, a unified interface is provided. This is great for interacting with third-party APIs, especially those with REST capabilities like Twitter, Facebook, and MailChimp.

• HTTP Basics
• About RESTful APIs
• Using the WordPress HTTP API

HTTP Basics

We all know HTTP in practice. In fact, if this is your first time on the web, you’ve already seen HTTP at work. HTTP is a network protocol used to transfer all files and data (resources) across the Internet.

There are basically two parts: HTTP requests and HTTP responses (i.e., a transaction). Both requests and responses are very similar in structure; they all have four parts:

• An initial line (request line)
• Zero or more header lines
• An empty line
• An optional body content

The Initial Line

Requests use the initial line to send three pieces of information: the method name, the path, and the HTTP version. For example, when viewing a blog page, you will see this in the first line of the request:

GET /blog HTTP/1.1

Responses also provide three pieces of information, though slightly different: the HTTP version, a response code, and a response description. When a request is made to a blog, it will send an HTTP response with the following initial line:

HTTP/1.0 200 OK

Headers

Headers contain various pieces of information about the request or response. HTTP 1.1 defines 46 header types, but only one (for requests only) is required – the “Host” header. See the screenshot from Chrome Developer Tools, showing some headers from a request:

Header Example

Body

The body usually contains the data for the requested resource. If you send a GET request to a blog, you should receive the HTML required to render the page (resource) in the body content.

More Information

That’s all you need to know about HTTP for now. We’ll mainly be focusing on method names (GET, POST, etc.), headers, and the body. If you want to learn more, a good article is James Marshall’s explanation of HTTP, a very nice intro to HTTP.

About RESTful APIs

RESTful APIs, or REST methods, are designed to provide a simple and standard way to interact with an application. It’s commonly used in conjunction with HTTP to create an easily understandable interaction system. It’s based on paths and HTTP verbs.

HTTP verbs are the same as the method names we saw earlier; the most common ones are: GET, POST, PUT, DELETE. When used with paths, we can build a meaningful system:

GET /post/1/ would be used to retrieve the post with an ID of 1. DELETE /post/1/ would be used to delete the same post. We could also use PUT /post/1/ to update it, providing relevant information in the request body and headers.

You can see that by simply appending the HTTP version to the code above, we actually have the initial line of an HTTP transaction, which is one of the reasons why this system is so powerful.

Using the WordPress HTTP API

With all of this knowledge, we can easily grasp how the WordPress HTTP API works. There are four methods for making requests and intercepting responses:

• wp_remote_get()
• wp_remote_post()
• wp_remote_head()
• wp_remote_request()

The first two functions are self-explanatory; they use the GET and POST methods, respectively, in the request. The third function uses the HEAD method, which we haven’t discussed. This method is used only to retrieve the headers of the response. If we only need some metadata about a resource, this can save a lot of overhead. The last function is a generic function where you can specify the method to use in the function’s arguments.

We can use five additional functions to retrieve specific parts of the response. These are basically shortcuts to guide us through the large amount of data we receive:

• wp_remote_retrieve_body()
• wp_remote_retrieve_header()
• wp_remote_retrieve_headers()
• wp_remote_retrieve_response_code()
• wp_remote_retrieve_response_message()

First HTTP Request

Let’s do a quick test by retrieving the header information from a blog. You can do this anywhere in your plugin or theme, but obviously, you should do it in a testing environment to make sure you don’t output unwanted text on a live site.

$response = wp_remote_head( 'https://www.example.com/blog' );
var_dump( $response )

From the response, you can see that the body part is empty (because we used the HEAD method), and all the headers are displayed. To get only the headers without all the other array members, we can use the wp_remote_retrieve_headers() function.

array (size=5)
  'headers' =>
    array (size=13)
      'server' => string 'nginx' (length=5)
      'date' => string 'Wed, 22 Jul 2015 14:22:07 GMT' (length=29)
      'content-type' => string 'text/html; charset=UTF-8' (length=24)
      'connection' => string 'close' (length=5)
      'vary' => string 'Accept-Encoding' (length=15)
      'x-pingback' => string 'https://www.example.com/xmlrpc.php' (length=29)
      'x-powered-by' => string 'HHVM/3.8.0' (length=10)
      'link' => string '<https://api.w.org/>; rel="https://api.w.org/"' (length=68)
      'x-frame-options' => string 'DENY' (length=4)
      'x-content-type-options' => string 'nosniff' (length=7)
      'strict-transport-security' => string 'max-age=31536000' (length=16)
      'content-encoding' => string 'gzip' (length=4)
  'body' => string '' (length=0)
  'response' =>
    array (size=2)
      'code' => int 200
      'message' => string 'OK' (length=2)
  'cookies' =>
    array (size=0)
      empty
  'filename' => null

Understanding APIs

Twitter API Interface

For developers, the biggest hurdle is the amount of new stuff you need to make API calls work. You need to understand HTTP, how to make requests, and how to authenticate correctly; otherwise, every call will fail. Let’s look at an example of the Twitter API since they provide very detailed documentation.

We’ll look at application-only authentication (which is a simpler process), following the same steps that Twitter suggests. Make sure to create a Twitter application before starting.

You should be able to add the code below anywhere in your theme or plugin, and make sure to use a testing site!

Step 1: Encoding the CONSUMER KEY and SECRET

After creating the application, you should get a CONSUMER KEY and a CONSUMER SECRET. To make things easy, let’s create constants to store this information.

define( 'TWITTER_CONSUMER_KEY', '12disnir382jeqwdasd23wdasi' );
define( 'TWITTER_CONSUMER_SECRET', '23wdajskduhtrq2c32cuq9r8uhuf' )

The documentation lists three steps to create the encoded version of these:

• URL encode the KEY and SECRET
• Concatenate them with a colon
• Base64 encode the entire string

In PHP, this is easy to do!

$key = urlencode( TWITTER_CONSUMER_KEY );
$secret = urlencode( TWITTER_CONSUMER_SECRET );
$concatenated = $key . ':' . $secret;
$encoded = base64_encode( $concatenated );

Step 2: Get a Bearer Token

Instead of using an actual password, you send your encoded string (using your API credentials) to Twitter, and you’ll receive a temporary pass that’s valid for a certain amount of time. To do this, we’ll make an HTTP request, which is what Twitter says:

• The request must be an HTTP POST request.
• The request must include an Authorization header with the value of Basic.
• The request must include a Content-Type header with the value of application/x-www-form-urlencoded;charset=UTF-8.
• The request body must be grant_type=client_credentials.

Let’s start with the basics. A POST request is needed, so we’ll use wp_remote_post(). This function takes parameters; the first is the URL, and the second contains optional arguments. The URL is https://api.twitter.com/oauth2/token, and we’ll use the second argument to handle all the other requirements.

$args = array(
  'headers' => array(
    'Authorization' => 'Basic ' . $encoded,
    'Content-Type' => 'application/x-www-form-urlencoded;charset=UTF-8'
  ),
  'body' => 'grant_type=client_credentials'
);
$response = wp_remote_post( 'https://api.twitter.com/oauth2/token', $args );

The headers need to be added as an array, with the header type as the key and the value as the array member’s value; the body should be a string. If successful, you should see a response similar to the following.

array (size=5)
  'headers' =>
    array (size=23)
      'cache-control' => string 'no-cache, no-store, must-revalidate, pre-check=0, post-check=0' (length=62)
      'content-disposition' => string 'attachment; filename=json.json' (length=30)
      'content-encoding' => string 'deflate' (length=7)
      'content-length' => string '142' (length=3)
      'content-type' => string 'application/json;charset=utf-8' (length=30)
      'date' => string 'Wed, 22 Jul 2015 14:47:37 GMT' (length=29)
      'expires' => string 'Tue, 31 Mar 1981 05:00:00 GMT' (length=29)
      'last-modified' => string 'Wed, 22 Jul 2015 14:47:37 GMT' (length=29)
      'ml' => string 'A' (length=1)
      'pragma' => string 'no-cache' (length=8)
      'server' => string 'tsa_b' (length=5)
      'set-cookie' => string 'guest_id=v1%3A14375720938219946; Domain=.twitter.com; Path=/; Expires=Fri, 21-Jul-2017 14:47:37 UTC' (length=100)
      'status' => string '200 OK' (length=6)
      'strict-transport-security' => string 'max-age=631138519' (length=17)
      'x-connection-hash' => string 'd8b10926f99dwef93rd7edbe5a71a97a' (length=32)
      'x-content-type-options' => string 'nosniff' (length=7)
      'x-frame-options' => string 'SAMEORIGIN' (length=10)
      'x-response-time' => string '34' (length=2)
      'x-transaction' => string 'ef0ebwefweece62ef' (length=16)
      'x-tsa-request-body-time' => string '0' (length=1)
      'x-twitter-response-tags' => string 'BouncerCompliant' (length=16)
      'x-ua-compatible' => string 'IE=edge,chrome=1' (length=16)
      'x-xss-protection' => string '1; mode=block' (length=13)
  'body' => string '{"token_type":"bearer","access_token":"AAAAAAAAAAAAAAAAAAAAAFoafQAAAAAAqg%2BxmuH83hjsod6crH5bKTUX9Arc%3D5dWpp0XCTDjyiXxMC7LDLg8JbzPdGlCsJi2R1qjY1FMksTAFyG"}' (length=155)
  'response' =>
    array (size=2)
      'code' => int 200
      'message' => string 'OK' (length=2)
  'cookies' =>
    array (size=1)
      0 =>
        object(WP_Http_Cookie)[303]
          public 'name' => string 'guest_id' (length=8)
          public 'value' => string 'v1:143757645770219946' (length=21)
          public 'expires' => int 1500648457
          public 'path' => string '/' (length=1)
          public 'domain' => string '.twitter.com' (length=12)
  'filename' => null

The main highlight of all of this is the access token that can be found in the response body. Now let’s use a WordPress function to retrieve it. Referring to the previous example, we can use the following code to get the access token:

$body = wp_remote_retrieve_body( $response );
$body = json_decode( $body, true );
$access_token = $body['access_token'];

Step 3: Using the Bearer Token

The last step is to use this bearer token in all other API calls. We need to add it as an “Authorization” header with the value: Bearer [bearer_token]. Let’s make a simple API call that will retrieve a user’s latest tweets using the user_timeline path.

Finally, the $tweets variable will contain an array of tweets. You can use the various properties of this array to display the tweets or process the data.

$url = 'https://api.twitter.com/1.1/statuses/user_timeline.json?screen_name=twitterdev&count=3';
$args = array(
 'headers' => array(
   'Authorization' => 'Bearer ' . $access_token,
 ),
);

$response = wp_remote_get( $url, $args );
$tweets = json_decode( wp_remote_retrieve_body($response), true )

Key Takeaways

* The WordPress HTTP API provides a standardized way to make HTTP requests within WordPress.
* Understanding HTTP basics (requests, responses, headers, body) is crucial for working with APIs.
* RESTful APIs use HTTP verbs (GET, POST, PUT, DELETE) and paths to interact with applications.
* The `wp_remote_get()`, `wp_remote_post()`, `wp_remote_head()`, and `wp_remote_request()` functions are used to make different types of HTTP requests.
* Functions like `wp_remote_retrieve_body()`, `wp_remote_retrieve_headers()`, etc., help retrieve specific parts of the response.
* Authentication is often required when interacting with APIs, and the WordPress HTTP API can handle different authentication methods.

FAQ

* **Q: What is the WordPress HTTP API used for?**
* A: It’s used for making HTTP requests to external services and APIs from within WordPress.

* **Q: Why should I use the WordPress HTTP API instead of cURL or `file_get_contents`?**
* A: It provides a standardized and more secure way to make HTTP requests, handling things like SSL verification and error handling more gracefully.

* **Q: How do I handle errors when using the WordPress HTTP API?**
* A: Check the response for errors using `is_wp_error()` and retrieve the error message using `$response->get_error_message()`.

* **Q: Can I use the WordPress HTTP API to upload files?**
* A: Yes, you can use `wp_remote_post()` and set the `multipart` argument to `true`.

* **Q: How do I set custom headers in my HTTP request?**
* A: Use the `headers` argument in the `wp_remote_get()`, `wp_remote_post()`, or `wp_remote_request()` functions.

Summary

As you can see, connecting to external services using the WordPress HTTP API isn’t difficult. Many modern APIs today are built on the same REST principles – once you learn one, you’ll quickly pick up others.

Remember to use the body whenever the documentation asks you to, and when headers are needed, just add the required amount. Then, view the response, turn it into an array, get the data you need, and use it; it’s that simple.

If anyone has used particularly good or bad APIs before, or if you have some tips and tricks for using the WordPress HTTP API, let us know in the comments!