... and a little mod_rewrite :-)

Here I'm going to show you how you can implement a RESTful interface using exclusively JavaScript code on the client side, and PHP on the server side. In between them we are going to use minimal Apache's mod_rewrite for some URI manipulation.

All the source code for this example as well as a working version of it can be found here on the Labs section. And here's a ZIP archive containing the same files for download.

Files

Let's get started by listing the files that will be part of the solution:

myResource.php - Contains the PHP implementation of the service. In this case I have chosen to include the code for different methods in the same file.

client.html and client.js - Markup and JavaScript code for the client that will consume our service. On this example you'll see different methods being invoked and different responses being handled.

.htaccess -  Contains the rule that translate the RESTful URL and redirects the request to our PHP implementation. The file htaccess.txt contains a copy of the hidden file's content for easy viewing.

RESTful URI's

Now, the URI's we want for this example have the following form:

/api/myResource/[RESOURCE_ID]

For example:

http://ccswf.ca/labs/restfulPhpAjax/api/myResource/1234

That means that if we want to get information for the resource number 1234 we need to perform a GET request to that URI. If we wanted to delete that same resource we would issue a DELETE HTTP request and if we wanted to list all resources we would omit the id part. You get the idea.

So the rule that interprets that URL is inside the .htaccess file and looks like this:

RewriteRule ^api/(myResource)(/\d{0,8})?$ serviceImpl/$1.php

It basically tells Apache to let our PHP file handle all requests involving that resource. The regular expression allows for the id to be optional.

The actual parsing of the URL will be made in the PHP code. Let's see how that is done.

Service Implementation (Server-Side)

The property that allows us to read the original URI is REQUEST_URI in the $_SERVER global object . In our example we are only interested on the id part of the string so that's what we extract:

$parts = preg_split("/\//", $_SERVER["REQUEST_URI"]);
$resourceId = $parts[count($parts) - 1];

The other thing we have to take care of  with PHP is detecting the HTTP method invokes. The property for that is called REQUEST_METHOD. And here it is in action:

if($_SERVER["REQUEST_METHOD"] == "GET") {
...
} else if($_SERVER["REQUEST_METHOD"] == "DELETE") {
...
}

Our service only supports methods GET and DELETE, but any HTTP method can be used.

Some HTTP requests like POST allow data to be passed to the server. The easiest way to access that data from PHP is by opening the php://input pseudo-file. Like this:

$input = file_get_contents("php://input");

And finally, after we do our stuff -like deleting the resource- we send back a HTTP response code to the client. That is done by using the built-in header function. Here's an example:

header($_SERVER["SERVER_PROTOCOL"] . " 404 Not Found");

On that line the protocol taken from the $_SERVER global object, although we know it will probably be a version of HTTP. In this particular case, the response code we have chosen to return is a 404 code, as in "couldn't find a resource with the given ID". That response will be decoded on the client side.

Client Implementation (Service Consumer)

Let's jump to the client implementation to see how those methods are actually invoked. In a nutshell, what we do is use the AJAX technique to send requests to the URI. The JavaScript object that will do all that for us is the XMLHttpRequest object.

So in our single client.js Javascript file you will find something similar to the following code.

var req = new XMLHttpRequest();
...
req.open("PUT", "api/myResource/1234");
req.send("Some resource data");

On that snippet we call the PUT method on a specific resource identifier, passing along some text as data. What's been cut out from there is the actual handling of the response, which will look something like this:

req.onreadystatechange = function() {
  if(req.readyState == 4) {
    if(req.status == 200) {
      // Ok 
      var returnedData = req.responseText;
     } else if (req.status == 404) {
       // Not found
       var statusInfo = req.statusText;
     } else if (req.status == 501) {
       // Not implemented, this should not happen
     }
  }
}

Notice how the different response codes are handled explicitly and how the response data is obtained from responseText property.

So that is pretty much all you need to know in order to create a neat client-server interaction RESTstyle. Hope you liked it. Don't be afraid to add your questions or comments.

See you next time!