RESTful Web Services with Zend Framework

Introduction

We've all had over a week to absorb the new Zend Framework 0.20 release. Personally I've been loving it. The Zend Framework meets my requirements with flying colours.



For an upcoming project I intend implementing a RESTful web service. Back a few months ago when tinkering with the idea of a Technorati class for the Zend Framework, a reply from Davey Shafik highlighted the existence of a Zend_Rest_Client proposal. That proposal has since been implemented, and is now available from the Framework's incubator directory. Also available is the focus of this tutorial - Zend_Rest_Server.



So let's all gather round and do some tinkering. You can download the code put together here from restful_tutorial.tar.gz or restful_tutorial.zip

What is REST?

I'll start with the obligatory REST introduction.



REST stands for Representational State Transfer (see also Representational State Transfer. In an attempt to simplify understanding REST, consider the world wide web. Using the web, all resources can be requested using either a simple GET or POST request. Each resource has a unique URI. Additionally each resource can be cached since it's (for a period at least) static. It works really well for images, webpages and such.



Applying this concept to a web service means fitting all possible requests into a small number of possible URI resources. If you take an example of a Library Web Service, you may wish to request details for a specific book. As a webservice all we're looking for is the associated data for this book (as XML). A possible URI could be:



http://www.example.com/book/isbn/xxx or

http://www.example.com/book?isbn=xxx (using a query string)



Simply, a GET request to this URI would return the books data as XML as identified by the ISBN Number. What's important is that this URI always returns the same resource - it's cacheable. It might be updated in time, but the URI is persistent.



If we want the data for a book called "Ulysses", a possible URI could be:



http://www.example.com/book?title=Ulysses



Of course we could use the Zend Framework's parameter approach using a Zend Controller route. For good measure you can constrast this approach with XML-RPC (see [ XML-RPC]) where requests are themselves XML containing a method name and sometimes parameter data, etc. Cutting out such complex XML requests, and returning to basic URI usage (GET, POST, PUT, DELETE) is the main difference between REST and RPC.



This tutorial takes a look at the new Zend_Rest_Server component. In doing so we implement a simple web service, and assess for advantages and disadvantages.

Application Setup

We'll start off by implementing a simple REST server using Zend_Rest_Server. The class is part of the Zend Framework which we'll use as the basis for our mini application. To start we need to setup a basic application using the Zend Framework. The directory structure we'll use is as follows:

restful-tutorial/

    /application

            /controllers

            /servers

    /library

    /data

The Zend Framework itself has the ./library/Zend directory placed in the application's ./library directory. The Framework's ./incubator/library/Zend directory is placed within the application's ./library/incubator directory.



In the applications root directory we place the bootstrap index.php file and and a .htaccess file. The index.php is as follows.



Our .htaccess file includes:

RewriteEngine on

RewriteRule . index.php



php_flag magic_quotes_gpc off

php_flag register_globals off

Adding Population Data to Database

Being a web service, we need data to serve! To start I'm creating one table for MySQL with prepopulated data. We'll pretend our REST service allows users to retrieve notes originally stored by a NoteIt application. There will be one table - "notes". Here's the SQL for a MySQL database you can import.

Adding URIs For Client Requests

Our web service will expect clients to make GET requests for this data. Oddly enough, users will not need all the data. To allow users append conditions to their requests, while maintaining a RESTful service we will design a number of possible urls to handle such conditions.



Rather than using a query string, I'll be difficult and rely on paramaters set as part of the URI. These will be parsed from the URI by Zend_Controller_RewriteRouter.



The basic conditions we might expect to meet are retrieving notes based on:



# user

# tag

# user and tag

# id



We can create URI paths for these. In the example urls below, service stands for a Zend Framework ServiceController class, and note stands for a NoteAction() method on that Controller. The remainder of the url constitutes a parameter list.



# http://www.example.com/service/note/user/XXX

# http://www.example.com/service/note/tag/XXX

# http://www.example.com/service/note/user/XXX/tag/XXX

# http://www.example.com/service/note/id/XXX



We could also allow a client to grab all notes for all users, or all notes for all tags - but we'll restrict ourselves to the above possibilities. By keeping the possible URIs as simple as possible we make them easy to remember - since we're using the Zend Framework we can avoid using a query string and instead rely on the internal routing process which parses that part of the URI above our parent directory (which holds index.php) into controller, action and parameters.



The Zend Framework's core MVC components allow us to define and place requirements on additional routes using Zend_Controller_RewriteRouter and Zend_Controller_Router_Route. If we take the first URI, we can assemble a route of the form:


Using the above as a template we can quickly create new routes for each URI we intend supporting in our RESTful web service. We can replace the previous index.php @todo comment with the following:

ServiceController Class

Ignoring IndexController, we'll run our service from a NoteAction() method on a ServiceController class, i.e. URI after our root url will be /service/note.



With our valid routes defined, we can now implement the ServiceController class. The Controller will currently only require a single method - NoteAction(). The new Action will access the parameters parsed from the URI, and setup a Zend_Rest_Server instance to handle the current request.



The actual work entailed in gathering the data needed to build a response is offloaded on a standalone class we'll call App_Rest_Server_Note. In the absence of an application name, App_ is as good a class prefix as any. This class will will hold all the specific methods Zend_Rest_Server may need to call.



The ServiceRestController (saved as ServiceController.php to ./application/controllers):



The NoteAction() method isn't hugely complicated. It grabs an array of all parameters obtained from the URI. Once we have the parameters, we need to filter them since they are afterall user input data. Once filtered, the filtered data is built into a new $request array. We additionally add an extra 'method' entry to this array containing the method to call on the handler class.



With parameters filtered, we then instantiate a Zend_Rest_Server object and hand the $request array to it. We also provide the Server instance with the name of the class it should use to handle the request and gather the data required for(a response.



There are some complications however. Our original assumption on the service would be that the parameters from the client can vary. Usually we could do something simple in the handler method on App_Rest_Server_Note like use func_get_args() to cope with variable numbers of parameters. Unfortunately, Zend_Rest_Server is very strict - you must have one public method for all possible parameter combinations on the handler class. In addition, the naming of such parameters must be identical to the names of the original parameters (i.e. see the variable requirements on our preset routes in index.php).



The only way to get around this, is adding additional code to compensate.



Before we go further, we also need a default IndexController class:

App_Rest_Server_Note Handler

To gather the data needed by Zend_Rest_Server to create a response, we will create an App_Rest_Note_Handler class. Because of the above limitations, we must have a specific public method for all possible parameter combinations. To avoid code duplication (our service only runs a simple SQL query with a varying WHERE condition), these simply delegate to a private getNotes() method.



The App_Rest_Server_Note class (saved as App_Rest_Server_Note to ./application/servers)


Once you get over the public method handoffs (the getNotes() method needs to know the name of parameters so it has both keys and values when building the SQL). The rest is simple. We run the query after establishing a database connection, and proceed to build an XML response.

Building an XML Response

It's here we find another Zend_Rest_Server limitation. First of all, the Server class can create an XML response itself, but it cannot yet handle a multidimensional array. To return the results, we therefore must create our own XML response. The referenced getXML() method for this follows.


This method can build the expected response. If no data actually exists, we'll get an empty <response> element. In addition we add a <status> element for success. Zend_Rest_Server will use a similar element for any failures and include a failure message.



As of 0.20, Zend_Rest_Server does not support JSON, YAML or other formats for a response. We're restricted to XML until support for those formats are added.

Trying It Out

With all pieces in place, including the database (edit db.ini for your details) we can try a test url:



http://yourserver/service/note/user/2



The response resulting from this requests (just use your browser - we're not implementing a service client):