Building RESTful Services with Zend Framework

REST simply dictates that a given resource has a unique address, and that you interact with that resource using HTTP verbs. The standard verbs utilized are:

• GET: retrieve a list of resources, or, if an identifier is present, view a single resource
• POST: create a new resource with the data provided in the POST
• PUT: update an existing resource as specified by an identifier, using the PUT data
• DELETE: delete an existing resource as specified by an identifier
• OPTIONS: to set the http request options

The standard URL structure used is as follows:

/resource - GET (list) and POST operations
 /resource/{identifier} - GET (view), PUT, and DELETE operations

What the REST paradigm provides you is a simple, standard way to structure your CRUD (Create-Read-Update-Delete) applications. Due to the large number of REST clients available, it also means that if you follow the rules, you get a ton of interoperability with those clients.

It is really so easy to create RESTful routes for your MVC application, as well as to handle the various REST actions via Zend_Rest_Controller or action controllers. Zend_Route allows you to define RESTful controllers at several levels:

• You can make it the default route, meaning that unless you have additional routes, all controllers will be considered REST controllers.
• You can specify modules that contain RESTful controllers.
• You can specify specific controllers per module that are RESTful.

As examples:

'blog' => array(
 'type' => 'Segment',
 'options' => array(
 'route' => '/api/blog[/:id]',
 'defaults' => array(
 'controller'=>'blogController',
 ),
 'constraints' => array(
 'id'=>'[a-f0-9]{40}',
 ),
 ),
 ),

To define a RESTful action controller, you can either extend AbstractRestfulController, or simply define the following methods in a standard controller extending Zend_Controller_Action (you will need to define them regardless):

To define a RESTful action controller, you can either extend AbstractRestfulController, or simply define the following methods in a standard controller extending Zend_Controller_Action (you’ll need to define them regardless):

class BlogController extends AbstractRestfulController{
 // Handle GET and return a list of resources
 public function get() {}

// Handle GET and return a specific resource item
public function getList() {}

// Handle POST requests to create a new resource item
public function create() {}

// Handle PUT requests to update a specific resource item
public function update() {}

// Handle DELETE requests to delete a specific item
public function delete() {}

// Handle OPTIONS requests to set Allow header with allowed HTTP methods
public function options() {}
}

For those methods that operate on individual resources (get(), update(), and delete()), you can test for the identifier using the following:

if (!$id = $this->_getParam('id', false)) {
 // report error, redirect, etc.
 }

Responding is an art

Many developers are either unaware of or ignore the part of the specification that dictates what the response should look like.

For instance, in classic REST, after performing a POST to create a new item, you should do the following:

• Set the HTTP response code to 201, indicating “Created”
• Provide a representation of the newly created item

Similarly, with PUT requests, you simply indicate an HTTP 200 status when successful, and show a representation of the updated item. DELETE requests should return an HTTP 204 status (indicating success – no content), with no body content.