A Guide To HTTP And The WordPress HTTP API

In preparation, I thought I’d take a look at how HTTP works in general and how you can use native WordPress functions to work with it, opening up your products to integration with Twitter, Facebook, Mailchimp and all sorts of other tools.

In this article – part 1 of 2 – I’ll show you the basics of HTTP requests, how they are structured, the information they contain and how to make sense of it. In part 2 we’ll put our knowledge into practice – through WordPress.

What Is HTTP

HTTP is the main protocol used on the web today, it stands for Hypertext Transfer Protocol and it is responsible for showing you HTML, images and more. HTTP clients – like your browser – send requests to HTTP servers which send back a response.

For example, if you point your browser to Kinsta.com you are sending a request to Kinsta’s servers. The server reads your request, figures out what you need (we’ll talk about how this happens soon) and sends back a response which contains the HTML code for the page. Your browser reads the response and renders the HTML code for you on screen.

HTTP Request Basics

Any transaction between a client and a server starts with an HTTP request. The two most important parts of a request is the method name and the URL of the requested resource. Let’s start with the latter.

Resources

A resource is piece of data that can be identified with a URL. For example: http://myblog.com/my-awesome-article will probably return an HTML file – the code needed to render your awesome article.

Method Names

Method names identify the type of action you want to perform on the resource. Browser almost always use GET which indicates that you would like to retrieve the resource.

Other methods include POST for creating new items, PUT for updating items, DELETE for deleting items and HEAD for grabbing header information.

These method names, along with URLs provide the basis of REST APIs. You could send a get request to /article/4 to retrieve article 4. You could also send a PUT request along with some data to modify it, or a DELETE request to remove it.

The Structure of HTTP

HTTP requests and responses are very similar from a structural point of view. Each one has four distinct parts:

• An initial line which is different for the request and the response
• Optional headers which contain information about the request or response
• A blank line
• Optional body content

1. The Initial Line

For requests, the initial line contains three pieces of information: the method name, the resource path and the HTTP version used. Here’s how it might look:

GET /users/4 HTTP/1.1

Note that this line contains the local relative path not the full URL. The base URL is sent in a header (the Host header), we’ll take a look at headers soon.

Responses also contain three pieces of information: the HTTP version, the status code and a reason that describes the status code.

HTTP/1.1 302 Moved Temporarily

For a list of all status codes and a little bit about each, take a look at the HTTP Status Codes Specification, it’s all pretty clear there.

2. Headers

Headers are essentially name-value pairs of information. The previously mentioned Host header is a good example, in fact, it is the only required header in HTTP 1.1. Headers give you more control and more information.

The Accept header let’s you specify the type of content you will allow in a request. The Accept-Language header let’s you control the language of the content you are willing to accept. Both are forms of content negotiation.

The Authorization header is one you will use heavily when working with APIs to access authorization-only actions like deleting a Tweet or accessing your user account.

3. Body

The body is where the resource is returned, or where further explanation may be given if you’ve run into an error. You can use your language of choice to read the data from the body and display it, or use it internally to deal with errors.

Using HTTP

I found that understanding HTTP was enormously helpful when negotiating documentation for third-party APIs. What complicates the use of HTTP is that you usually use it within a programming language which means you need to be familiar with how that language implements HTTP as well as with HTTP itself.

Once you’ve made the request you’ll need to read the response, know what information to grab from it, perhaps even run the response through some functions to convert it into the format you need. Once you have that information you can display it, save it in a database or otherwise manipulate it.

HTTP itself is not difficult, but the tasks you must perform aside from making/receiving a request can mount up pretty quickly, masking the simplicity of HTTP in a shroud of complexity. In addition, many APIs will require you to authenticate which adds another layer on top of it all.

cURL

cURL is one way of interacting with HTTP but is rather complex. It can be used from the terminal, but PHP also has cURL support. To grab the contents of a URL you could use the following in the terminal.

curl http://kinsta.com

The problem is that cURL usage in the terminal can get a but complex. To view only header information you would need to use the following form:

curl -s -D - http://danielpataki.com -o /dev/null

You can view a list of all parameters but chances are you’ll be using cURL in your web application, so let’s look at cURL in PHP, here’s how to get the content of the same page:

$ch = curl_init();
$timeout = 5;
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $timeout);
$data = curl_exec($ch);
curl_close($ch);
echo $data;

This is still a bit clunky but by using the PHP Guide you can figure out what’s what.

Using WordPress

cURL is great, but adding headers and dealing with returned information is not as easy as you may be used to if you’ve been working with nicely coded PHP classes and functions. Luckily WordPress has us covered with its HTTP API. We’ll look at it in detail in the next article, for now, here’s an example with WordPress’ native function, including the addition of headers:

$request = wp_remote_get('https://api.twitter.com/1.1/statuses/user_timeline.json?screen_name=kinsta, array(
    'headers' => array(
        'Authorization' => 'Bearer ' . $token,
    ),
));

Summary

HTTP is the basis for everything we do on the web and knowing what goes on in a request and a response gives us great troubleshooting capabilities and allows us to control our applications better.

By getting to grips with HTTP basics you will be able to utilize external APIs faster and better, knowing exactly what to do with the information given to you in API guides.

In the next post in the series I’ll look at how you can handle HTTP data with WordPress and how you can hook WordPress up with a third party service very easily.