Implement a Rest API with the Zend Framework

Edit: Recent developments in the 1.9 version of the Zend Framework has caused much of this information to become obsolete. Please consider Zend_Rest_Server deprecated and use Zend_Rest_Controller instead. I will write an updated article once I have experimented with it. Thanks to the other developers who brought this to my attention.

As a developer and I admit that I judge the utility of a website by the availability of an API so that I can leverage it in my own projects. Most popular web services offer an API of some sort such as Flickr, Blip.TV, Youtube, Twitter, Facebook, etc. The most popular way to implement an api that is accessible to all styles of developers is to implement it using REST. In a nutshell, REST is a method of utilizing the HTTP protocol to send and retrieve information. REST leverages the various request types that HTTP supports (GET,POST,PUT,DELETE) while web browsers typically only use GET and POST to fetch web pages and submit form information. I won’t go into the intricacies of REST other than to note that the primary idea behind REST is that web services are presented in an object oriented fashion. REST urls typically comprise of a reference to an object or service of some type and an action to perform on the object. Parameters that are required to perform the requested action are provided as post variables in the header rather than as part of the url.

An example of a typical REST url for retrieving a photo would be:

http://typical.webservice.com/rest/photo/1

When accessed using the GET method of the HTTP protocol, the assumption is that you want to retrieve this photo. The response might be the image itself, or more typically it will be a JSON or XML encoded response containing a url to the image stored on a CDN. Alternately, if this same url is accessed using a DELETE request, the photo would instead be deleted and an encoded status report would be returned.

Chances are if you’re reading this article you already know all of this and just want to know how to implement this using the Zend Framework. This example utilizes controllers in an MVC style application. The first thing to understand is that REST is not implemented in the controller itself, instead the controller simply serves as a broker for various classes we have for handling different types of REST requests. Most of the boilerplate functionality is handled by an instance of  Zend_Rest_Server so all we have to do is implement our service.

In keeping with the REST philosiphy you will want to visualize how your web service will be accessed in terms of objects and their associated actions. It might help to draw up some use cases, but in this case lets keep going with our photo example. Let’s assume we want to allow users to upload photos, retrieve them, delete them, etc. Using this example, the first place to start naturally would be a class that represents Photos. Before that however, make sure you have set up your MVC application how you like it. Make sure you have written an appropriate class to represent your photo models complete with your persistence layer implementation. If you have no idea what i’m talking about, take a look at my application skeleton examples.  For those who are ready, we can implement our REST handlers now.

I like to start with a base class that contains functionality that will need to be shared across all the REST handlers. Here is a simple base class that we can extend.

This class implements one method right: authenticate(). Most web services require some form of authentication and/or api key to prevent abuse so this application shouldn’t be any different. This method is obviously just a stub as your authentication method can be whatever you prefer.

Next lets implement a default REST handler that responds to generic requests.

This class implements getVersion() which responds with the current version of the web service software. I call it the default handler because it will serve as a fallback handler when no context is specified in the REST url. The name of the method is important because that is the name of the action used in the url (Example: http://webservice.com/rest/getVersion).  This method takes two arguments ($userid and $apikey). You will notice that all REST methods will minimally require these arguments. The purpose of these arguments is so a developer implementing your API can provide their credentials. The names of these arguments map directly to the name of your request parameters (http://webservice.com/rest/getVersion?clientid=1&apikey=1234567890). These parameters can be provided as post variables as well.

All REST methods will always return an encoded response using a custom response generator Rest_Response.

The purpose of this class is to generate responses in a uniform and consistent structure. Each response regardless of the context or action should use the same structure which makes a developer implementing your API want to pull out his hair less than if each response required a completely different parser.  This class provides a static method Generate() which takes an associative array as its argument which it converts into xml. Optionally, Generate() takes a status argument which indicates whether the request Succeeded or failed. This is helpful in case the response parser needs to respond differently in the event of a failure.

So let’s make another REST handler that handles requests for photos.

This handler is a little more sophisticated. It responds to requests to upload photos, retrieve them and delete them. Just like the default handler, each method requires credentials and some take additional arguments. The upload method receives the file and generates a database record for the photo which has an id associated with it which can be returned in the response. The get() method takes an id for an argument that it uses to retrieve a database record for a photo and then returns the information associated with it. Similarly, delete() takes an idea and deletes the associated photo from the database and returns a status report.

So now we have handlers for our REST operations but we haven’t yet seen where the controller fits into all of this. As I said earlier, the controller doesn’t only acts as a broker for the REST requests. In this application we have a single controller RestController with a single method restAction()

restAction() looks pretty gnarly at first glance. Believe me when I was figuring out how to do this it started of pretty simple but rapidly evolved to handle various use cases as most code does. I’ll go over it step by step.

Obviously in order to satisfy all of the requirements of both the controller and our REST handlers we need some workable routes which directs REST requests to this action.

The first route allows us to make requests in the default context. This allows us to call http://webservice.com/rest/getVersion

The next route allows us to specify a context. For example: http://webservice.com/rest/photo/get?id=1

So first things first we need to disable the view and layout plugins since all we are interested in getting back from this action is either pure XML or JSON
. If we don’t disable the layout or view engines they will go looking for non-existant templates, or worse find some and wrap out XML or JSON in HTML.

Next we need to grab the request parameters. We strain out the parameters that get automatically appended by the controller infrastructure because they are not needed by the REST handlers.

Next we determine if there is a context in the request. This allows us to determine which REST handler we need to instantiate and invoke.

Now we instantiate a Zend_Rest_Server object and assign our custom handler. I’m sure this can be streamlined to be a little more dynamic.

And now we let the handler do its thing. If we fail to set returnResponse(), the REST server will ignore everything after this line and send its response back to the requester directly. By setting this to true, we ensure the handler will return its response to the controller so we can do some housekeeping.

In order to be truly flexible with the needs of other developers we really should offer a variety of response formats. Some developers prefer JSON while others need XML. It’s a good idea to accept a format parameter that allows the developer to specify the preferred format or assign a default format otherwise. Once we know what format to use, we need to set the Content-Type header and then send the response back to the requester.

There’s not much more to it than that, although as a footnote, I subclassed the default Zend_Rest_Server object because I wanted to to return custom XML in the event of an uncaught exception in the REST handlers.

It’s very important that you are diligent about catching exceptions and handling them properly otherwise the response can be ruined with garbage such as error messages outside of the XML or JSON, or worse, they could be blank. To use this simply instantiate this class instead of Zend_Rest_Server. So with this knowledge go forth and create. The web needs more clean and robust web services.