Over the last few days I have been trying to use the Zend_Rest_Controller along with the Zend_Rest_Route to make a RESTful application for an API that I am working on. It is very easy to get things setup with these components and I will cover that now. You might be asking yourself why do I have to use both components, why is it not rolled into one nice component. The answer is really basic and if you look at the source code for the Zend_Rest_Controller you will see that it is solely an abstract class that defines the methods required for use with the Zend_Rest_Route. When your controller extends from the Zend_Rest_Controller it just forces you to implement the indexAction(), getAction(), postAction(), putAction() and deleteAction() methods. Technically you do not have to extend from Zend_Rest_Controller so long as you implement these methods in all of your RESTful controllers. It is good design to extend the class though as it will throw exceptions for developers who forget to add one of these methods. Without the methods the Zend_Rest_Route cannot route the request to the matching RESTful methods.

In order to get started you have to add a method to your Bootstrap file. This method can be named anything you like however it has to start with _init.

I choose to call mine _initRoutes() because this is where I would put all of my routes. The first thing you need to do is make sure that the frontController has been setup and this is done with the call to $this->bootstrap('frontController'). Once that is completed you get the instance for your FrontController and create the new route object. You get the Router object from the FrontController and simply add your route. If you look at how I added the route you will see that I named the route 'default'. This is so that the Rest Route will become the default route for my application. This allows your entire application to be restful. You might be asking why that matters, couldn't you have more than one route in your application? The short answer is yes however if you add any other routes then you are going against the principals of rest by adding non restful routes to your application.

Once this portion is completed all you have to do is create a controller that extends from Zend_Rest_Controller as such:

With this in place your application is now RESTful. There is only one problem that I am facing. We are building a RESTful web API at work and I have been trying to put the API version in the URL. Currently we are using modules so I would expect to be able to do something like the following: /2.0/products/11 and have it call the getAction and return the product details for the product with the ID of 11. However in ZF you cannot name modules with the 2.0 syntax. Therefore I created the modules named m2m0 which stands for major 2 minor 0. I needed to find a way to actually route this properly. The Zend_Rest_Route would not route it properly by default because in the internals it checks the dispatcher to see if you have all the valid modules/controllers/actions defined. It fails when it looks for a module named 2.0 and falls back to use the 'default' module. I have tried using a FrontController plugin like you can with all of the other routes. The normal ZF routes do not check with the dispatcher to ensure that the modules/controllers/actions that are routed to are proper and thats where the issue lies. After trying everything I could think I ended up extending the Zend_Rest_Route and copying the match() method into the new file which overrides the match() method in Zend_Rest_Route. I was able to add my 4 lines of code to do the mapping for the module names but it also led to duplication of around 100 lines of code from the base Zend_Rest_Route class. This is not the best method but until I hear more from the ZF team it is the only work-around I have found. I have created a ticket on the Issue Tracker to see what the internal developers think about this issue.