So, what makes REST better? In simplest of terms, REST helps in data exchange with a set of well-established mechanisms and protocols and focuses more on minimum workload, unlike many other similar methods that are heavier and bulkier in terms of operation. As such, REST focuses more on efficiency and speed and offers cross-platform data exchange. This is, by far, the biggest advantage of using RESTful services.

Now, as the Internet expands, so do the devices and technologies associated with it. With more and more mobile devices coming to the fore and coding standards being curated to adhere to specific norms, REST APIs too are evolving in order to meet purer standards of implementation. Thus, while the implementation of REST API remains more or less uniform, the modus operandi of RESTful services coded in different languages or platforms can have some minor differences. This is obvious to some extent because REST is an architectural style and not an architectural standard, and unlike HTML5, you cannot expect a W3C compliant guideline for REST API.

Now that we have covered the basic details about REST API and its major benefits, it is time to actually get started with REST in practice. In the next section, I will now talk a bit about how REST requests and responses work across different platforms and languages. Plus, the coming section will also be discussing the basic functioning of REST, including how simple and complex requests work. This, of course, is more of a practical consideration and less of a puritan one, and you can skip the coming section and move straight on to WordPress REST API if you want, but for the sake of information and for those who might be interested in learning more about REST API across different services and platforms, let us discuss REST properly before heading toward its relation with WordPress.

The architecture of RESTful services is pretty straightforward and we can briefly summarize its main components as follows:

REST is more of a style and less of a standard, so there are not many design principles to consider. In general, this is what you should follow:

Also, for documenting a REST service, you can use Web Services Description Language (WSDL) or Web Applications Description Language (WADL). Both are feature-rich, but WSDL offers more flexibility as it does not bind itself to Simple Mail Transfer Protocol (SMTP) servers, whereas WADL is easier to read and interpret. And if either of them does not appeal to you, a simple HTML document too can suffice.

Say, we need to query a given database for user details of a user with ID 1191. Using web services and Simple Object Access Protocol (SOAP), we will be doing something such as the following:

<?xml version="1.1"?> 
<soap:Envelope 
xmlns:soap="http://www.w3.org/2001/12/soap-envelope" 
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"> 
<soap:body pb="http://www.example.com/database"> 
<pb:GetUserDetails> 
<pb:UserID>1191</pb:UserID> 
</pb:GetUserDetails> 
</soap:Body> 
</soap:Envelope> 

The preceding code will give us an embedded XML file inside a SOAP response envelope.

And how will we do this using REST? The following way: http://www.example.com/database/UserDetails/1191.

Yes, that is all. It is a simple URL with GET request, and the response will give us the raw data, that is, the details of the user with ID 1191. While in SOAP, we needed multiple libraries to parse the response, in REST, we just need to pass the simple URL. We can even test the API directly right within the browser as a simple request.

Of course, the preceding example is a simplified case, and if need be, REST libraries do exist. However, as it becomes clear, REST is way simpler than web services and other counterparts.

For complex operations, the methodology remains similar. Let us refine the preceding query and look for the user with first name Sample and last name User as follows: http://www.example.com/database/UserDetails?firstName=Sample&lastName=User.

As we can see, for longer parameters, we are including the parameters within the body of the HTTP POST request. At this point, it is useful to discuss REST requests in themselves.

For simpler queries of a read-only nature, GET is the de facto standard. However, for read-only queries that are complex in nature, POST requests can be used. Of course, POST requests are also used for queries that can change the state of the data and deal with creation, updating, and deletion of data.

If you are wondering how to distinguish a simple query from a complex one, consider this: when reading a blog, you send a GET request as a simple query to open the page, but if you decide to post a comment on the blog post or share it via any of the social networks, you send a POST request with additional and more complex details.

And in terms of server responses, RESTful services can handle XML, CSV, and JSON. Each of these formats has its own advantages: XML, for example, is pretty easy to expand, CSV is compact and lightweight, whereas JSON is easy to parse. As you might have guessed by now, for WordPress REST API, JSON is the way to go, all thanks to JavaScript.

In Ruby, you can send HTTP requests using the Net::HTTP class. Thus, for GET requests, to look up the record number 1191 from the database of example.com, this is how you should do it:

require 'net/http' 
url = 'http://www.example.com/database/1191' 
resp = Net::HTTP.get_response(URI.parse(url)) 
resp_text = resp.body 

In the preceding example, we are using an object to handle the HTTP response code.

Similarly, for POST requests:

require 'net/http' 
url = 'http://www.example.com/database/user' 
params = { 
firstName =>'Sample', 
lastName =>'User' 
} 
resp = Net::HTTP.post_form(url, params) 
resp_text = resp.body 

Here again, we are using Net::HTTP class and using the post_form method for POSTing.

In Python, we already have the urllib2 module, so for RESTful actions, we just need to pass the GET request and then handle the response.

For example:

import urllib2 
url = 'http://www.example.com/database/1191' 
response = urllib2.urlopen(url).read() 
And for POST requests, we will once again rely on the urllib2 module: 
import urllib 
import urllib2 
url = 'http://www.example.com/database/user' 
params = urllib.urlencode({ 
'firstName': 'Sample', 
'lastName': 'User' 
}) 
response = urllib2.urlopen(url, params).read() 

In the preceding code, we are passing the request data as an extra parameter.

Personally, I have always relied on LWP, the library for WWW in Perl, for REST requests via HTTP.

For example, a GET request would look something like the following:

use LWP::Simple;
my $url = 'http://www.example.com/database/1191';
# sample request
my $response = get $url;
die 'Error getting $url' unless defined $response;

The preceding code is sufficient for a GET request without additional headers. For something more complex, you should consider creating a browser object in Perl and then handling it accordingly as follows:

use LWP;
my $browser = LWP::UserAgent->new;
my $url = 'http://www.example.com/database/1191';
my $response = $browser->get $url;
die 'Error getting $url' unless $response->is_success;
print 'Content type is ', $response->content_type;
print 'Content is:';
print $response->content;

Now, if you need to issue a POST request, you can follow the preceding approach again, and create a browser object and then pass the POST request as follows:

my $browser = LWP::UserAgent->new;
my $url = 'http://www.example.com/database/1191';
my $response = $browser->post($url,
[
'firstName' =>'Sample',
'lastName' =>'User'
];
);
die 'Error getting $url' unless $response->is_success;
print 'Content type is ', $response->content_type;
print 'Content is:';
print $response->content;

In the preceding example, we are using the browser object for issuing the POST request and then mapping the field names directly to the values.

For working with complex REST operations in Perl, you should consider learning more about LWP (the library for www in Perl).

C# as a programming language has structures and concepts of its own. For all practical purposes, you will need to use the .NET classes HttpWebRequest and HttpWebResponse for handling REST requests sent via HTTP.

For example, the following is what a typical GET request in C# would look like:

static string HttpGet(string url) { 
HttpWebRequest req = WebRequest.Create(url) 
as HttpWebRequest; 
string result = null; 
using (HttpWebResponse resp = req.GetResponse() 
as HttpWebResponse) 
{ 
StreamReader reader = 
new StreamReader(resp.GetResponseStream()); 
result = reader.ReadToEnd(); 
} 
return result; 
} 

What does the preceding code do? It simply passes a request and then returns the entire response as one long string. For backward compatibility, I would suggest that if you are passing parameters with your requests, it is advisable to properly encode them. You can use any of the native C# classes or methods for such encoding.

For passing POST requests, the method is similar to GETing, as shown in the following:

static string HttpPost(string url, 
string[] prName, string[] prVal) 
{ 
HttpWebRequest req = WebRequest.Create(new Uri(url)) 
as HttpWebRequest; 
req.Method = "POST";  
req.ContentType = "application/x-www-form-urlencoded"; 
 
// Creating a string, encoded and with all parameters 
// Assuming that the arrays prName and prVal are of equal length 
StringBuilder przz = new StringBuilder(); 
for (int i = 0; i < prName.Length; i++) { 
przz.Append(prName[i]); 
przz.Append("="); 
przz.Append(HttpUtility.UrlEncode(prVal[i])); 
przz.Append("&"); 
} 
 
// Encoding the parameters 
byte[] frDat = 
UTF8Encoding.UTF8.GetBytes(przz.ToString()); 
req.ContentLength = frDat.Length; 
 
// Sending the request 
using (Stream post = req.GetRequestStream())  
{  
post.Write(frDat, 0, frDat.Length);  
} 
 
// Getting the response 
string result = null; 
using (HttpWebResponse resp = req.GetResponse() 
as HttpWebResponse)  
{  
StreamReader reader = 
new StreamReader(resp.GetResponseStream()); 
result = reader.ReadToEnd(); 
} 
 
return result; 
} 

Once again, we have encoded the parameters in the preceding code and have accepted a request and returned the response.

When using REST requests in Java, the concept is similar to that of C#, and an experience Java coder can easily pick up the ropes. Basically, you use the HttpURLConnection class and invoke its object type. Following is an example for a GET request:

public static String httpGet(String urlStr) throws IOException { 
URL url = new URL(urlStr); 
HttpURLConnection conn = 
(HttpURLConnection) url.openConnection(); 
if (conn.getResponseCode() != 200) { 
throw new IOException(conn.getResponseMessage()); 
} 
// Buffering the result into a string 
BufferedReader drdr = new BufferedReader( 
new InputStreamReader(conn.getInputStream())); 
StringBuilder sb = new StringBuilder(); 
String line; 
while ((line = drdr.readLine()) != null) { 
sb.append(line); 
} 
drdr.close(); 
conn.disconnect(); 
return sb.toString(); 
} 

In the preceding code, we are issuing a GET request and then accepting the response as one long string. If you wish to use it in your projects, you might wish to tweak it a bit, probably with the help of try or catch. Plus, note that for backward compatibility, it is advisable to encode the parameters that are passed with the request URL.

Now, for POST requests, this is how we will work:

public static String httpPost(String urlStr, String[] prName, 
String[] prVal) throws Exception { 
URL url = new URL(urlStr); 
HttpURLConnection conn = 
(HttpURLConnection) url.openConnection(); 
conn.setRequestMethod("POST"); 
conn.setDoOutput(true); 
conn.setDoInput(true); 
conn.setUseCaches(false); 
conn.setAllowUserInteraction(false); 
conn.setRequestProperty("Content-Type", 
"application/x-www-form-urlencoded"); 
 
// Creating form content 
OutputStream out = conn.getOutputStream(); 
Writer writer = new OutputStreamWriter(out, "UTF-8"); 
for (int i = 0; i < prName.length; i++) { 
writer.write(prName[i]); 
writer.write("="); 
writer.write(URLEncoder.encode(prVal[i], "UTF-8")); 
writer.write("&"); 
} 
writer.close(); 
out.close(); 
 
if (conn.getResponseCode() != 200) { 
throw new IOException(conn.getResponseMessage()); 
} 
 
// Buffering the result into a string 
BufferedReader drdr = new BufferedReader( 
new InputStreamReader(conn.getInputStream())); 
StringBuilder bsbs = new StringBuilder(); 
String line; 
while ((line = drdr.readLine()) != null) { 
bsbs.append(line); 
} 
drdr.close(); 
 
conn.disconnect(); 
return bsbs.toString(); 
} 

Once again, we are accepting a POST request with a parameter and then passing the response accordingly.

Also, an experienced Java coder will be aware that Java is not the most popular language for web development and that its support for handlers for web connections is not at the top of its league. It is, therefore, a good idea to make use of packages and handlers from the Apache library for this purpose. However, we will evade this discussion now since it is beyond the scope of this book, and Java code is of little merit for someone whose primary focus might be on using RESTful services with WordPress.

Now, finally, we come to the language in which WordPress has been coded. Using REST in PHP is very easy because even the most basic PHP functions with a file-access model can work seamlessly with HTTP requests and URLs.

Therefore, for GET requests, virtually any file-reading function of PHP can do the job, such as fopen, for example:

$url = "http://www.example.com/database/1191";
$response = file_get_contents($url);

echo $response;

If you are passing parameters with GET requests, it might be a good idea to encode them.

However, while GET requests are pretty easy to handle, POST requests require a bit of work because you need to open a connection to the target server and then send the HTTP header information. For example, consider the following code:

function httpRequest($host, $port, $method, $path, $prms){ 
// prms is to map from name to value 
$prmstr = ""; 
foreach ($prms as $name, $val){ 
$prmstr .= $name . "="; 
$prmstr .= urlencode($val); 
$prmstr .= "&"; 
} 
// Assign defaults to $method and $port 
if (empty($method)) { 
$method = 'GET'; 
} 
$method = strtoupper($method); 
if (empty($port)) { 
$port = 80; // Default HTTP port 
} 
 
// Create the connection 
$sock = fsockopen($host, $port); 
if ($method == "GET") { 
$path .= "?" . $prmstr; 
} 
fputs($sock, "$method $path HTTP/1.1\r\n"); 
fputs($sock, "Host: $host\r\n"); 
fputs($sock, "Content-type: " . 
"application/x-www-form-urlencoded\r\n"); 
if ($method == "POST") { 
fputs($sock, "Content-length: " . 
strlen($prmstr) . "\r\n"); 
} 
fputs($sock, "Connection: close\r\n\r\n"); 
if ($method == "POST") { 
fputs($sock, $prmstr); 
} 
// Buffer the result 
$result = ""; 
while (!feof($sock)) { 
$result .= fgets($sock,1024); 
} 
fclose($sock); 
return $result; 
} 

Now, using the preceding sample function, we can issue a POST request as follows:

$resp = httpRequest("www.example.com", 
80, "POST", "/Database", 
array("firstName" =>"Sample", "lastName" =>"User")); 

We can also use the client URL request library (cURL) when working with RESTful requests in PHP.

Having covered all of that, let us finally discuss REST implementation in JavaScript. We will be saving the JSON issue for detailed discussion during the course of this book, so let's just focus on the traditional route now.

REST requests can be sent from client-side or in-browser JavaScript. If you have ever worked with an AJAX application, you have followed the REST design principles to a great extent, with the response being in JSON.

HTTP requests in JavaScript require the XMLHttpRequest object. The following function is a simple way to create the object:

function createRequest() { 
var result = null; 
if (window.XMLHttpRequest) { 
result = new XMLHttpRequest(); 
if (typeof xmlhttp.overrideMimeType != 'undefined') { 
result.overrideMimeType('text/xml'); // Or anything else 
} 
} 
else if (window.ActiveXObject) { 
result = new ActiveXObject("Microsoft.XMLHTTP"); 
} 
return result; 
} 

Now that you have created the object, you are ready to send HTTP requests. However, the XMLHttpRequest object, while it can send requests, cannot return values by default. So it is better to have a callback function that can be invoked when your request is completed.

Thereafter, you are ready to send the request. For a GET request, the approach is fairly simple:

req.open("GET", url, true); 
req.send(); 
And for POST requests: 
req.open("POST", url, true); 
req.setRequestHeader("Content-Type", "application/x-www-form-urlencoded"); 
req.send(form-encoded request body); 

As you can see, sending HTTP requests in JavaScript is pretty easy and you just need to call the appropriate function.

WordPress has had an API of its own for quite a while, and as such, the API part is nothing new for WordPress developers. In fact, if you have ever coded a plugin for WordPress, you might already be aware that WordPress uses its API to interact with the plugin.

However, the old WordPress API is ideal for internal processes such as a plugin, but hardly useful for external services. REST API, on the other hand, is perfect for allowing WordPress to interact with services outside of WordPress.

In other words, with REST API on board, WordPress can interact with services and websites on the Internet, which may or may not use WordPress! Yes, WordPress REST API can interact and exchange information with any service on the web that might be coded in a different language, running a different code structure, or be of a different nature.

Similarly, you can also let external services interact with WordPress content with the help of REST API. Thus, any service or website making use of REST API can now interact with your WordPress website and its posts, pages, custom post types, taxonomies, users, and more with ease, as long as it runs on the HTTP protocol (which is supported by nearly all of the Internet nowadays).

In HTTP, the POST, GET, UPDATE, and DELETE requests will allow you to create, read, update, and delete content, respectively. We shall revisit these steps with code examples in later chapters of this book, as we progress through our journey with REST API in WordPress.

WordPress REST API comes with safety measures of its own, such as cookie-based and OAuth authentication.

Cookie-based authentication is useful for plugins and themes, whereas OAuth authentication (relying on http://oauth.net/) can be used to authenticate desktop, mobile, and web clients. This will allow WordPress REST API to define limited and clearly defined data exchange; the external service will be able to view and edit only that section of data that is made available to it, nothing else.

As such, you can build clients that let you create and publish a blog using WordPress, but offer a minimal and more interactive interface than the WordPress admin panel. Since JSON is natively supported by both Android and iOS, WordPress REST API is a special boon for mobile developers who can build mobile applications that make use of REST API for interacting with WordPress platforms while running on Android or iOS.

As already stated, REST API enables WordPress to interact with services and sites that might not be built on WordPress, and vice versa. However, what can we expect from such cross-platform and third-party support?

Well, this means we can now procure content and interact with data from any other platform as long as we follow the HTTP route. For example, we can now allow Ruby on Rails (RoR) applications to interact with WordPress websites, while WordPress too can interact with systems that are otherwise not coded in PHP.

This is especially useful for folks who are working with third-party tools and need to interact with WordPress regularly. Furthermore, frontend developers can now focus on the frontend of their website without having to worry about the backend, all thanks to WordPress REST API.

Even more so, REST API can be used by WordPress developers to take their plugin and themes to non-WordPress platforms and other CMSs.