fbpx
The Complete Guideline to Use WordPress HTTP API

The Complete Guideline to Use WordPress HTTP API

The WordPress HTTP API consists of a bunch of functions that will help you make HTTP calls much easier. There is no need to fiddle with file_get_contents or cURL ever again, just a single unified interface. This is awesome for interacting with third-party APIs, especially REST-full ones like Twitter, Facebook, MailChimp, and others.

The Basics of HTTP

We’ve all seen HTTP action before. In fact, if this is your first time on the web and it’s the first article you’re reading, then you’ve already seen HTTP working its magic. HTTP is a network protocol used to deliver all files and data (resources) through the Interwebs.

Basically, the equation has two parts: the HTTP request and the HTTP response. Both the request and the response have a very similar structure, both have four parts:

  • A start line
  • Zero or more header lines
  • A blank line
  • An optional message body

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 the main page of the ThemeRally blog, you would see this on the initial line of the request.

GET /blog/ HTTP/1.1

The responses also provide three pieces of information, albeit somewhat different: The HTTP version, the response code, and a description of the response. Making a request to the main ThemeRally blog will send an HTTP response with the following leading line:

HTTP/1.0 200 OK

Headers

The headers contain several bits of information about the request or response. HTTP 1.1 defines 46 types of headers, but only one is required (for requests only), the “Host” header. Take a look at the screenshot from my Chrome developer tools showing some of the headers submitted along with a request to the main ThemeRally blog:

http-api-request-header-in-wordpress

Body

The body usually contains data about the requested resource. If you send a GET request to the main ThemeRally blog, you should receive the necessary HTML to display the page (the resource) in the body content.

About the REST API

The Rest API or REST methodology aims to provide a simple and standard way of interacting with an application (you can learn more about the basics of the WordPress REST API here ). It is often used in conjunction with HTTP to create a highly understandable system of interactions. It is based on HTTP verbs and routes.

The HTTP verbs are the same as the names of the methods that we saw previously, the most common are: GET, POST, PUT, DELETE. We think PUT is the only uncertain one here, think of it as an update command. By using these verbs together with the routes we can build a meaningful system:

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

I’m sure you can see that just by adding an HTTP version to our above codes, we have the initial line of an HTTP transaction, which is just one of the reasons this system is so powerful.

Using the WordPress HTTP API

Armed with all that knowledge we can easily understand how the WordPress HTTP API works. The four methods used to make requests and intercept responses are:

  • 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, something we haven’t talked about yet. This method is used to retrieve only the headers of a response. This can save a lot of overhead if we only need some metadata about a resource. The final function is generic, you can specify which method you want to use within the parameters of the function.

There are five additional functions that we can use to retrieve specific parts of the answer. These are basically shortcuts to navigate the mass 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()

Our First HTTP Request

Let’s do a quick test by retrieving the information from the ThemeRally blog header. You can do this anywhere within a plugin or theme, but obviously, you must be within a staging environment to make sure you don’t cast spam on a live site.

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

As you can see from the answer we get below, the body section is empty (since we are using the HEAD method) and all the headers are displayed. To select only the headers without all the other members of the array we could use the function wp_remote_retrieve_headers().

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://themerally.com/xmlrpc.php' (length=29)
      'x-powered-by' => string 'HHVM/3.8.0' (length=10)
      'link' => string '; rel="https://github.com/WP-API/WP-API"' (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)
      'x-themerally-cache' => string 'HIT' (length=3)
      '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-wordpress-api

The biggest barrier we have seen for developers is the myriad of new things they need to put in place to make an API call work. You need to know about HTTP, how to make requests, and also how to authenticate properly, without that every call will fail. Let’s look at an example via the Twitter API, as they have great documentation.

We will be looking at app-only authentication (which is an easier flow), we will follow the same steps Twitter suggests. Before you start, make sure you create a Twitter app.

You should be able to add the code below anywhere within a theme or plugin, but as we mentioned before, be sure to use a test site!

Step 1: Encrypt the Consumer’s Key and Secret Code

Once you’ve created an app, you should have a consumer key and secret code handy. To make things easier, we are going to create constants that keep this information for us.

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

The three steps to create an encoded version of these are set out in the docs:

  • The URL encodes the consumer key and consumer secret code
  • Concentrate them with a colon
  • Base64 encodes the entire string

In PHP this will be pretty easy to do, here it is!


$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 your real password, you send your encrypted string (which uses your API credentials) to Twitter and receive a temporary pass that is valid for a specified time. To do this we will make an HTTP request, this is what Twitter has to say:

  • The request must be an HTTP POST request.
  • Must include an authorization header with the value of Basic.
  • Also 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. We know we need a POST request, so we will use wp_remote_post(). The function leads to the parameters; the first is the URL, the second contains optional arguments. The URL will be the second parameter 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 must be added as an array, the header type being the key, the value of the array member; the body must be a string. If you are successful, you should see a response similar to the one below.

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 feature of all this is the access token that can be found in the response body. Let’s get that back now using our handy WordPress functions. Continuing with our previous example, we could take the access key using the following code:

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

To learn more, you can also visit: HTTP API

Step 3: Use the Bearer Token

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

$url = 'https://api.twitter.com/1.1/statuses/user_timeline.json?screen_name=danielpataki&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 )

At the end of all that, the variable will contain a series of tweets. You can use various properties of this array to display the tweet or manipulate the data.

You May Also Read: WordPress then and now – prospects for the future

Conclusion

As you can see, using the WordPress HTTP API to connect to external services is not that difficult. Many of today’s modern APIs are built around the same REST principles – once you learn one, you will get used to the others very quickly.

Keep in mind that when the documentation asks you to use the body, use the body, and when it asks for the header, you just have to add as many as necessary. Then look at the answer, convert it to an array, take the data you need, and use it, it’s that simple.

If anyone has worked with a particularly good or bad API before, or if you have any tips and tricks for using the WordPress HTTP API, let us know in the comments.

Last Update:

About the Author

One Comment

Comments are closed.