Zend Framework: Zend_Controller_Router_Route_Rest Component Proposal

Proposed Component Name	Zend_Controller_Router_Route_Rest
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Controller_Router_Route_Rest
Proposers	luke.crouch@gmail.com Matthew Weier O'Phinney - Zend Liaison
Revision	1.0 - 23 Feb 2008: Started. 1.0 - 15 May 2008: changed from Route class to full-on Router class. 1.0 - 15 May 2008: changed back to Route class 2.0 - 01 Jan 2009: updated Route class for ZF 1.7 compatibility 2.0 - 30 Jun 2009: development started under ZF-7109 (wiki revision: 45)

This component will operate as a Route class of the Rewrite Router.
This component will route to Modules and Controllers based on URI tokens.
This component will route to specific Actions based on HTTP request types.
This component will support overloaded-POST-based routing for PUT and DELETE request types.
This component will route to some special Actions based on URI tokens.
This component will include an abstract Zend_Controller_Action class for implementation reference.
This component will allow for designating specific REST Modules and/or Controllers

4. Dependencies on Other Framework Components

Zend_Controller

5. Theory of Operation

A RESTful routing paradigm for Zend_Controller should behave as follows:

Request method URI Module_Controller::action

GET /product/ratings/ Product_RatingsController::indexAction()

GET /product/ratings/id/:id Product_RatingsController::getAction()

GET /product/ratings/new Product_RatingsController::newAction()

GET /product/ratings/id/:id/edit Product_RatingsController::editAction()

POST /product/ratings Product_RatingsController::postAction()

PUT /product/ratings/id/:id Product_RatingsController::putAction()

DELETE /product/ratings/id/:id Product_RatingsController::deleteAction()

POST /product/ratings/id/:id
_method=PUT Product_RatingsController::putAction()

POST /product/ratings/id/:id
_method=DELETE Product_RatingsController::deleteAction()

6. Milestones / Tasks

Milestone 1: Working prototype checked into the incubator supporting use cases #1
Milestone 2: Unit tests exist, work, and are checked into SVN.
Milestone 3: Initial documentation exists.

7. Class Index

Zend_Rest_Route
Zend_Rest_Controller
Zend_Rest_PutHandler

8. Use Cases

9. Class Skeletons

<?php 
/**
 * Zend Framework
 *
 * LICENSE
 *

 * This source file is subject to the new BSD license that is bundled
 * with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://framework.zend.com/license/new-bsd
 * If you did not receive a copy of the license and are unable to
 * obtain it through the world-wide-web, please send an email

 * to license@zend.com so we can send you a copy immediately.
 *
 * @package    Zend_Controller
 * @subpackage Router
 * @copyright  Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
 * @version    $Id: Module.php 8972 2008-03-21 18:48:44Z thomas $
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */ 
 
/** Zend_Controller_Router_Route_Interface */ 
require_once 'Zend/Controller/Router/Route/Interface.php'; 
 
/** Zend_Controller_Dispatcher_Interface */ 
require_once 'Zend/Controller/Dispatcher/Interface.php'; 
 
/** Zend_Controller_Request_Abstract */ 
require_once 'Zend/Controller/Request/Abstract.php'; 
 
/**
 * Rest Route
 *
 * Request-aware route for RESTful modular routing
 *
 * @package    Zend_Controller
 * @subpackage Router
 * @copyright  Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */ 
class Zend_Rest_Route extends Zend_Controller_Router_Route_Module 
{	
	/**
     * Specific Modules to receive RESTful routes
     * @var array
     */
	protected $_restfulModules = null;

	/**
     * Specific Modules=>Controllers to receive RESTful routes
     * @var array
     */
	protected $_restfulControllers = null;
	
    /**
     * Constructor
     *
     * @param array $defaults Defaults for map variables with keys as variable names
     * @param Zend_Controller_Front $front Front Controller object
     */
    public function __construct(Zend_Controller_Front $front,
    	array $defaults = array(), 
    	array $responders = array())
    {
        $this->_defaults = $defaults;

        if($responders)
			$this->_parseResponders($responders);

        if (isset($front)) {
            $this->_request = $front->getRequest();
            $this->_dispatcher = $front->getDispatcher();
        }
    }

    /**
     * Matches a user submitted request. Assigns and returns an array of variables
     * on a successful match.
     *
     * If a request object is registered, it uses its setModuleName(),
     * setControllerName(), and setActionName() accessors to set those values.
     * Always returns the values as an array.
     *
     * @param Zend_Controller_Request_Http $request Request used to match against this routing ruleset
     * @return array An array of assigned values or a false on a mismatch
     */ 
    public function match($request)
    { 
        $this->_setRequestKeys();

        $path = $request->getPathInfo();
        $values = array(); 
        $params = array(); 
        $path   = trim($path, self::URI_DELIMITER); 
 
        if ($path != '') { 
        	 
            $path = explode(self::URI_DELIMITER, $path); 
            
            // Determine Module
            $moduleName = $this->_defaults[$this->_moduleKey];
            if ($this->_dispatcher && $this->_dispatcher->isValidModule($path[0])) {
            	$moduleName = $path[0];
            	if ($this->_checkRestfulModule($moduleName)) {
	                $values[$this->_moduleKey] = array_shift($path); 
	                $this->_moduleValid = true;             			
            	}
            } 
             
            // Determine Controller
            $controllerName = $this->_defaults[$this->_controllerKey];
            if (count($path) && !empty($path[0])) {
            	if ($this->_checkRestfulController($moduleName, $path[0])) {
            		$controllerName = $path[0];
                    $values[$this->_controllerKey] = array_shift($path);
                    $values[$this->_actionKey] = 'get';
            	} else {
            		// If Controller in URI is not found to be a RESTful
            		// Controller, return false to fall back to other routes
            		return false;
            	}
            }
            
            // Check for leading "special get" URI's
            $specialGetTarget = false;
            if (count($path) && array_search($path[0], array('index', 'new')) > -1) {
            	$specialGetTarget = array_shift($path);
			}

			// Digest URI params
            if ($numSegs = count($path)) { 
                for ($i = 0; $i < $numSegs; $i = $i + 2) { 
                    $key = urldecode($path[$i]); 
                    $val = isset($path[$i + 1]) ? urldecode($path[$i + 1]) : null; 
                    $params[$key] = $val; 
                } 
            }
            
            // Check for trailing "special get" URI
            if (array_key_exists('edit', $params))
            	$specialGetTarget = 'edit';

			// Determine Action
            $requestMethod = strtolower($request->getMethod());
            if ($requestMethod != 'get') {
				if ($request->getParam('_method')) {
					$values[$this->_actionKey] = strtolower($request->getParam('_method'));
				} else {
					$values[$this->_actionKey] = $requestMethod;
				}
            } elseif ($specialGetTarget) { 
                $values[$this->_actionKey] = $specialGetTarget;
            }
             
        } 
        $this->_values = $values + $params; 
        
        return $this->_values + $this->_defaults; 
    }
 
    /**
     * Assembles user submitted parameters forming a URL path defined by this route
     *
     * @param array $data An array of variable and value pairs used as parameters
     * @param bool $reset Weither to reset the current params
     * @return string Route path with user submitted parameters
     */ 
    public function assemble($data = array(), $reset = false, $encode = true) 
    { 
        if (!$this->_keysSet) { 
            $this->_setRequestKeys(); 
        } 
 
        $params = (!$reset) ? $this->_values : array(); 
 
        foreach ($data as $key => $value) { 
            if ($value !== null) { 
                $params[$key] = $value; 
            } elseif (isset($params[$key])) { 
                unset($params[$key]); 
            } 
        } 
 
        $params += $this->_defaults; 
 
        $url = ''; 
 
        if ($this->_moduleValid || array_key_exists($this->_moduleKey, $data)) { 
            if ($params[$this->_moduleKey] != $this->_defaults[$this->_moduleKey]) { 
                $module = $params[$this->_moduleKey]; 
            } 
        } 
        unset($params[$this->_moduleKey]); 
 
        $controller = $params[$this->_controllerKey]; 
        unset($params[$this->_controllerKey]); 
 
        foreach ($params as $key => $value) { 
            $url .= '/' . $key; 
            $url .= '/' . $value; 
        } 
 
        if (!empty($url) || $controller !== $this->_defaults[$this->_controllerKey]) { 
            $url = '/' . $controller . $url; 
        } 
 
        if (isset($module)) { 
            $url = '/' . $module . $url; 
        } 
 
        return ltrim($url, self::URI_DELIMITER); 
    }
    
    /**
     * Tells Rewrite Router which version this Route is
     *
     * @return int Route "version"
     */
    public function getVersion()
    {
    	return 2;
    }
    
    private function _parseResponders($responders)
    {
    	$modulesOnly = true;
    	foreach ($responders as $responder){
    		if(is_array($responder))
    			$modulesOnly = false;
    	}
    	if ($modulesOnly){
    		$this->_restfulModules = $responders;
    	} else {
    		$this->_restfulControllers = $responders;
    	}
    }
    
    private function _checkRestfulModule($moduleName)
    {
    	if ($this->_allRestful())
    		return true;
    	if ($this->_fullRestfulModule($moduleName))
    		return true;
    	if ($this->_restfulControllers && array_key_exists($moduleName, $this->_restfulControllers))
    		return true;
    	return false;
    }
    
    private function _checkRestfulController($moduleName, $controllerName)
    {
    	if ($this->_allRestful())
    		return true;
    	if ($this->_fullRestfulModule($moduleName))
    		return true;
    	if ($this->_restfulControllers && array_search($controllerName, $this->_restfulControllers[$moduleName]) !== false)
    		return true;
    	return false;
    }
    
    private function _allRestful()
    {
    	return (!$this->_restfulModules && !$this->_restfulControllers);
    }
    
    private function _fullRestfulModule($moduleName)
    {
    	return ($this->_restfulModules && array_search($moduleName, $this->_restfulModules) !== false);
    }

}

abstract class Zend_Rest_Controller extends Zend_Controller_Action
{
   public function indexAction()
   {
      // select all from resource table;
      // put the resources onto view;
   }

   public function getAction()
   {
      // retrieve resource where id = URI param;
      // put resource onto view
   }

   public function editAction()
   {
      // retrieve resource where id = URI param;
      // put resource onto view
      // edit template shows form for editing the resource
   }

   public function newAction()
   {
      // new template shows form for submitting new resource
   }

   public function postAction()
   {
      // create new resource with POST values;
      // persist the resource
   }

   public function putAction()
   {
      // retrieve resource where id = URI param;
      // update resource with PUT values;
      // persist the updated resource;
   }

   public function deleteAction()
   {
      // delete resource where id = URI param;
   }
}

<?php
class Zend_Rest_PutHandler extends Zend_Controller_Plugin_Abstract
{
	public function preDispatch(Zend_Controller_Request_Abstract $request)
	{
		if ($this->_request->isPut()){
			$putParams = array();
			parse_str($this->_request->getRawBody(), $putParams);
			$request->setParams($putParams);
		}		
	}
}

Comments (Hide Comments)

Martel,

I actually started working on this again recently for a project and I ended up writing a Zend_Controller_Router_Rest class instead of a specific Route class. I updated my proposal in the wiki and would appreciate some feedback from you before I announce it to the mailing list. It actually works for me, but I'm sure it could use some cleanup and such ...

Luke, I don't really see anything in there that couldn't be used in the route class instead of a router. While overriding the router you're basically removing support for chaining different types of routing. And you render the URL view helper useless. And that's all. That's what you get by doing it in the router instead of a route class.

If you leave automatic module detection out, you don't even need the dispatcher instance (and router in fact shouldn't be aware of the dispatcher). All you need is the request object which will be passed to route instances in a very near future.

Posted by Michal Minicki at May 15, 2008 11:49 Updated by Michal Minicki

yeah, that's the best design, but RESTful routing needs the full request object and it's not currently available to Route classes, as you mentioned. I have this same code in a Route class as well, but it couldn't access the request object, so it's impossible to get the request method in a Route.

I'll just use this Router class in my project for now, but I will change this back into a Route and I think it will just have to wait until the request object is passed into Route instances. please keep me posted on how and when that advances. thanks.

Posted by Luke Crouch at May 15, 2008 12:08

Luke, pay attention to this issue:
http://framework.zend.com/issues/browse/ZF-777

As Matthew mentioned it in the last comment, I have a patch that keeps backwards compatibility intact. Basically this means you will just have to implement an additional interface (with setRequest method). And that's it - the request will be available for you on match().

Posted by Michal Minicki at May 15, 2008 12:34

As I have mentioned before, you now have a Request object passed as a first parameter to match() method on version 2 routes. Just extend abstract class to get this behavior by default.

Posted by Michal Minicki at Aug 04, 2008 01:18

Michal,

cool, thanks! I saw the issue update. is this presently only in trunk? is it slated to go out with next release?

Posted by Luke Crouch at Aug 04, 2008 08:16

What is the status of this class? What is the preferred method of implementing a RESTful Web Service?

Posted by Steve Wilhelm at Dec 03, 2008 23:01

I haven't done much with it. But, I have some free time now so maybe I can wrap it up this weekend.

I'll also be submitting another class or two to aid RESTful design. Watch this page for updates.

Posted by Luke Crouch at Dec 04, 2008 03:47

I've updated the use-case and class code of this proposal to match Route behavior of ZF 1.7.2. What are next steps for moving it into incubator?

Posted by Luke Crouch at Jan 01, 2009 12:08

Mark the proposal as ready for recommendation, and we'll pick it up on our next round of reviews.

Posted by Matthew Weier O'Phinney at Jan 01, 2009 13:01

I'm not sure I agree with the URI/request method mappings you outlined under "Theory of Operation". Traditional REST would do the following:

Request Method	URI	Module_Controller::action
GET	/product/ratings	Product_Ratings::listAction()
GET	/product/ratings/:id	Product_Ratings::getAction()
POST	/product/ratings	Product_Ratings::newAction()
PUT	/product/ratings/:id	Product_Ratings::updateAction()
DELETE	/product/ratings/:id	Product_Ratings::deleteAction()
POST	/product/ratings/:id	Product_Ratings::updateAction()
POST	/product/ratings/:id?delete	Product_Ratings::deleteAction()

The differences are around how get/new/update/delete work. When you POST with an identifier, it acts as an update; without an identifier, it attempts to create a new item.

Otherwise, the proposed solution makes sense.

One other item: It seems like this should include an extension to Zend_Controller_Action – perhaps Zend_Controller_Action_Rest and/or Zend_Controller_Action_Rest_Interface? That would simplify the creation of REST controllers, and ensure that they would work with the route.

Posted by Matthew Weier O'Phinney at Jan 08, 2009 11:17

Hmm ... I was going by behavior described in RESTful Web Services by Leonard Richardson & Sam Ruby. The spec seems to support it:

"The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. That resource might be a data-accepting process, a gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the URI in a PUT request identifies the entity enclosed with the request"
http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.6

I don't mind changing the names of the action methods, but the reason I have a separate newAction vs. a postAction is to allow the route to choose a controller action that serves a representation that will instruct the user agent how to compose the POST request that creates a new resource - e.g., an HTML form so /product/ratings/new returns an HTML form that POSTs to /product/ratings

The reason I didn't include query params in the URI for over-loaded POSTs is because the request method for over-loaded POST is still POST which means the params will be in the request body, not in the URI like that. It's effectively the same but I think the POST body params are more indicative of what's really happening.

I actually have an abstract Zend_Controller_Action_Rest class as well, but I'm not as sure of it, and I thought I'd submit them as separate proposals so users could use them separately. I wouldn't mind writing a Zend_Controller_Action_Rest_Interface to include with this proposal so we have an idea what the controller implementation should be.

So, if I change:

indexAction => listAction
putAction => updateAction
Add Zend_Controller_Action_Rest_Interface

Think that will be good for this proposal to move forward?

Posted by Luke Crouch at Jan 08, 2009 15:28

I was going based on other literature I've read, not the spec. I'm fine with identifying the identity as part of the payload – but make sure it's well documented what the various schemes are. Bonus points if you can make it configurable. That said, I really don't like using "new" to indicate a new record and "edit" to grab one to update; that's part of what REST tries to get around. If there is no entity identifier, it's a new record; POST updates the record.

Regarding the query parameters, it was unclear from your table that the _method=(PUT|DELETE) was a part of the payload; I thought it was part of the URI. Putting that in the payload is fine by me.

One last note on URIs: while the default ZF route uses key/value pairs, I really don't think it's necessary to do so with a REST route – and in fact makes the URLs look less clean. Let's go with traditional REST routes, and drop the id/:id in favor of just :id.

As for the action names, I think either index or list would work well for the collection of entities; maybe list could be an alias for index. I also do prefer using updateAction over putAction, as it identifies what's happening semantically.

Finally, regarding the Zend_Controller_Action_Rest class, I think abstract is fine (no need for an interface), and that it should be part of the proposal; it makes for a clean, full solution that users can develop on immediately.

Overall, very nice!

Posted by Matthew Weier O'Phinney at Jan 09, 2009 08:15

Re: edit and new ...

I agree that performing stateful operations via URI tokens is RESTless, but in this route's usage, 'edit' and 'new' denote resources/nouns - not operations:

'new' = the form (a resource) for creating a new resource
'edit' = the form (a resource) for editing an existing resource

This is basically to encourage "hypertext as the engine of application state." e.g., GET /resource/new delivers a representation (HTML page) that contains hypertext (<form method="post" action="/resource/">) that drives to another state of the application (creating a new resource). /resource/new DOES NOT perform any stateful operations, and does not respond to any requests other than GET.

With all that said, think it's fine to leave the 'new' and 'edit' actions in there as long as we make it explicit what their purpose is?

I'll work on dropping the key-value pairs for the identifier, but in using this route myself, I've found key-value params pretty useful. e.g., makes it easy to also support flexible identifiers like /name/:name or /modified_since/:timestamp.

I can also add a Zend_Controller_Action_Rest abstract class.

Posted by Luke Crouch at Jan 09, 2009 09:23

Aha - I was thinking of this more in terms of an XML/JSON REST service, not in terms of using it for HTML as well. With that in mind, I think it makes sense.

As for the /:id comment – you could think of it like Zend_Controller_Router_Route, where a /* means that anything following is key/value pairs. That would allow for urls like /wiki/SomePage/modified_since/2008-12-02 – which gives you the :id (SomePage) as well as extra key/value resources.

Posted by Matthew Weier O'Phinney at Jan 09, 2009 11:07

Zend Acceptance

This proposal is accepted for immediate development in the standard incubator. However, there are several changes/issues we would like to see addressed:

Rename to Zend_Rest_Route and Zend_Rest_Controller
Do not inject the dispatcher and request object in the route constructor. Instead, allow for optional injection of the front controller. As the dispatcher and request object could change prior to routing, injecting the front controller (or, if not present, pulling the singleton instance) will allow retrieving the instances as registered at execution time.
The abstract Zend_Rest_Controller should not include the newAction and editAction methods, but the route should still allow for them. The Zend team's feeling is that while these may be useful in REST applications that utilize HTML, the majority of REST applications will likely not utilize them, and the controller should not enforce their existence.
The route should allow each of the following scenarios:
- Acting as a fallback route, and route all matched requests as RESTful actions (this is the usage shown already in UC-01)
- Allow registering a specific module or array of modules as containing controllers with RESTful actions:
  // Only the module "api": $restfulRoutes = new Zend_Rest_Route('api', $front); // The modules "xml" and "json": $restfulRoutes = new Zend_Rest_Route(array('xml', 'json'), $front);
- Allow registering specific module => controller combinations as RESTful controllers:
  // The Service_RestController only: $restfulRoute = new Zend_Rest_Route(array('service' => array('rest')), $front); // The controllers: Json_RestController, Service_RestController, and Service_JsonController: $restfulRoute = new Zend_Rest_Route( array( 'json' => array('rest'), 'service' => array('rest', 'json'), ), $front );
  
  We feel that this API would allow for mixing RESTful controllers with other application controllers.
Finally, we have one concern regarding the matching of request method tokens. It cannot be assumed that the request is using a payload in a specific format; the request could be in JSON, XML, YAML, etc. As such, we request that if the matching is format specific, different subclasses be created for each specific format you intend to support (Zend_Rest_Route_Json, Zend_Rest_Route_Xml, etc.).

Posted by Matthew Weier O'Phinney at Jan 09, 2009 13:39

We can't put these classes into Zend_Rest. Frankly and simply, Zend_Rest has nothing to do with REST. It's just another XML-RPC implementation that ignores the uniform HTTP interface and other elements of RESTful design and architecture. I've made mention in the mailing lists before that it needs to be re-named and/or merged with Zend_XmlRpc.

REST is a different architectural style. These classes are Zend_Controller classes; they enhance functionality of Zend_Controller to enable REST architectural style and technical design. I'd rather keep them in the Zend_Controller package.

The request matching will never be format-specific, so there's no need for different sub-classes for different formats. In fact, I've used this exact route class really well with Zend_Controller_Action_Helper_ContextSwitch for building REST API that supports HTML, JSON, and XML simultaneously using only separate template files.

The injection of the dispatcher and the request into the constructor are inherited from Zend_Controller_Router_Route_Module. I'll alter this class to accept the front controller in the constructor, but that won't fix the problem in Module.

I'll remove the newAction and editAction from the Controller.

I'll also start work on designating specific module and controllers as RESTful via this route class.

Posted by Luke Crouch at Jan 09, 2009 19:08

Our plan is to deprecate Zend_Rest_Server, and potentially Zend_Rest_Client as well. We are well aware that they do not follow RESTful design, and this is one reason we are excited about your proposal, as it follows our desire to offer RESTful offerings. (The current Zend_Rest offerings were written well before we had a proposal process, and did not have sufficient review.)

The reason we would like these classes under Zend_Rest is two-fold. First, for developers looking for REST solutions in Zend Framework, they are unlikely to look in Zend_Controller; placing them under Zend_Rest makes finding them easier. Second, all other protocol and service specific classes in ZF have their own namespace: Zend_XmlRpc, Zend_Soap, Zend_Json, Zend_Dojo (form and view integration), etc – even if they have ties to other components. While your implementation is specific to the MVC, it allows us to group REST related components in a single location; documentation can then indicate how the various subcomponents are used and how they relate to other ZF components.

Thanks for pointing out the dispatcher/request injection in the module route; I'll create an issue to track that. Also, thank you for clarifying that the route is not format specific – this wasn't clear from the proposal, so it's good to know you've already taken care of that.

Posted by Matthew Weier O'Phinney at Jan 09, 2009 20:13

Okay, I feel better about that plan to deprecate the existing Zend_Rest classes. I agree it will be nice for users to find all the REST classes in a single place, and I think replacing the current Zend_Rest documentation with a guide on how to use these new RESTful classes will be a huge improvement.

Given that, should this proposal be re-named to Zend_Rest or something more like that? I should also mention that I also use a Controller plugin called 'RestHandler' for better support of PUT requests often used in RESTful HTML clients - i.e., to digest PUT request bodies of type 'x-www-form-urlencoded' and make the params available via $request->getParams(). Should I add this plugin class to the proposal as well?

Posted by Luke Crouch at Jan 11, 2009 11:54

No need to rename the proposal; the core of it is basically the same: a route class for RESTful requests.

Yes, do please include the RestHandler plugin; that way we can have a fairly complete REST offering for users. Please update the page to show the API of the plugin, as well as a sample use case.

Posted by Matthew Weier O'Phinney at Jan 11, 2009 12:12

Hi, Zend_Rest_Server will be deprecated. Does it mean that there will be some new Zend_Restful_Server/Client? If yes, will the server be consistent with the others soap/amf/xmlrpc server? (the server load a class/method and check the phpdoc)

Posted by Jerome Mouneyrac at Feb 10, 2009 20:11

No. Zend_Rest_Server currently follows that paradigm (introspection of class to determine method signatures), but that paradigm is not RESTful – it's simply another RPC-style service. This has caused confusion for many developers, and does not serve our users well. If you want to do RPC using XML... use XML-RPC.

Zend_Rest_Client will likely continue to live on. However, for most use cases when querying RESTful architectures, Zend_Http_Client is a better choice, as it gives more fine-grained control over the request headers and body, and in many cases is more intuitive when using RESTful architectures.

Posted by Matthew Weier O'Phinney at Feb 10, 2009 21:55

I assume if the route is configured for an entire module, all requests to the module should be routed RESTfully to all controllers in it?

Posted by Luke Crouch at Jan 11, 2009 11:31

Correct. The three scenarios we see are:

Route all requests as REST (UC-01) (unless specifically overridden with other routes)
Route all requests to a a given module as REST (i.e., all controllers in that module are REST controllers)
Route specific module/controller pairs as REST.

Posted by Matthew Weier O'Phinney at Jan 11, 2009 11:47

Does this solution allows to submit identifier with Umlauts and Slashes?

Example Use Case:
It should be possible to update products with the following identifiers:

ProductId: "Mü/120/abc"
ProductId: "Aß/230/def"

In this Use Case the identifiers contains Slashes as well as Umlauts. Submitting identifiers with slashes (and different character sets) shouldn't lead to misinterpreted parameters.

Remi

Posted by Remi at Jan 11, 2009 18:56

I hadn't thought of this but will look at supporting it. I'm not sure how to support both the flexible key-value url param identifiers AND slashes in the identifiers, but I'll give it a try.

Posted by Luke Crouch at Jan 12, 2009 07:24

I don't think you can support both use cases. I'd recommend that if you need slashes in your URLs for identifiers that you write logic to convert another character to slashes on the server side (when posted via the REQUEST_URI, that is).

Posted by Matthew Weier O'Phinney at Jan 12, 2009 08:40

I've updated the proposal and code to meet the acceptance criteria. Couple of things discussed but not implemented ...

I didn't drop the key-value URI scheme because I have found it easier to implement a flexible 'index' action - i.e., one that accepts an assortment of filtering params like /new_since/:timestamp/changed_since/:timestamp - if each of the params retain names. As I consider this though, I could change the route to pass key-value URI params for the 'index' route only, and all other routes could operate from the /:module/:controller/:identifier scheme. How important is this feature?

I left the putAction as putAction, simply because the route code is getting a little complex already, and also because I think it helps to reinforce users' implementation of the HTTP uniform interface in their controllers. Again I could re-consider this if we think it's very important.

Posted by Luke Crouch at Jan 12, 2009 10:15

Also, I need a bit of coaching on my next steps. I think I have svn access, but can I simply check-out the standard incubator repos? How's the best way to set up a test project to use my Zend_Rest stuff from the incubator repos but use Zend_Controller from regular repos?

Posted by Luke Crouch at Jan 13, 2009 19:55

Could support for the X-HTTP-Method-Override header be included to supplement the _method parameter for clients that (for whatever reason) offer limited or no support for methods other than GET and POST?

Posted by Matthew Turland at Feb 02, 2009 13:45

Sure. I'll include it when I start putting the code into the repos.

Posted by Luke Crouch at Feb 02, 2009 18:07

Luke, do you plan to have this ready for 1.8?

Posted by Wil Sinclair at Mar 18, 2009 16:01

Hopefully. When is 1.8 scheduled?

Posted by Luke Crouch at Mar 19, 2009 06:51

Surely I'm a little lost, but I cannot find your proposal at the standard incubator repository. Where it is?

On the other hand, you said:

As I consider this though, I could change the route to pass key-value URI params for the 'index' route only, and all other routes could operate from the /:module/:controller/:identifier scheme. How important is this feature?

I think this is a very important feature because it will allow a better integration with dojox.data.JsonRestStore

Posted by AJ at Jun 22, 2009 03:36

AJ,

I'm actually working on getting this code into SVN right now and I'm using a patch from Rafael Dohms to do exactly this.

Thanks for the feedback,
-L

Posted by Luke Crouch at Jun 22, 2009 05:33

Page Operations

Browse Space

Zend_Controller_Router_Route_Rest - Luke Crouch

Labels

Zend Framework: Zend_Controller_Router_Route_Rest Component Proposal

Table of Contents

1. Overview

2. References

3. Component Requirements, Constraints, and Acceptance Criteria