documentation/manual/en/module_specs/Zend_Controller-Router-Route-Rest.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect3 id="zend.controller.router.routes.rest">
   4     <title>Zend_Rest_Route</title>
   5
   6     <para>
   7         The <classname>Zend_Rest</classname> component contains a RESTful route
   8         for <classname>Zend_Controller_Router_Rewrite</classname>. This route
   9         offers a standardized routing scheme that routes requests by translating
  10         the <acronym>HTTP</acronym> method and the <acronym>URI</acronym>
  11         to a module, controller, and action. The table below provides an overview
  12         of how request methods and <acronym>URI</acronym>'s are routed.
  13     </para>
  14
  15     <table frame="all">
  16         <title>Zend_Rest_Route Behavior</title>
  17
  18         <tgroup cols='3' align='left' colsep='1' rowsep='1'>
  19             <colspec colname='method' />
  20             <colspec colname='URI' />
  21             <colspec colname='route' />
  22
  23             <thead>
  24                 <row>
  25                     <entry>Method</entry>
  26                     <entry><acronym>URI</acronym></entry>
  27                     <entry>Module_Controller::action</entry>
  28                 </row>
  29             </thead>
  30
  31             <tbody>
  32                 <row>
  33                     <entry><constant>GET</constant></entry>
  34                     <entry><filename>/product/ratings/</filename></entry>
  35                     <entry><methodname>Product_RatingsController::indexAction()</methodname></entry>
  36                 </row>
  37
  38                 <row>
  39                     <entry><constant>GET</constant></entry>
  40                     <entry><filename>/product/ratings/:id</filename></entry>
  41                     <entry><methodname>Product_RatingsController::getAction()</methodname></entry>
  42                 </row>
  43
  44                 <row>
  45                     <entry><constant>POST</constant></entry>
  46                     <entry><filename>/product/ratings</filename></entry>
  47                     <entry><methodname>Product_RatingsController::postAction()</methodname></entry>
  48                 </row>
  49
  50                 <row>
  51                     <entry><constant>PUT</constant></entry>
  52                     <entry><filename>/product/ratings/:id</filename></entry>
  53                     <entry><methodname>Product_RatingsController::putAction()</methodname></entry>
  54                 </row>
  55
  56                 <row>
  57                     <entry><constant>DELETE</constant></entry>
  58                     <entry><filename>/product/ratings/:id</filename></entry>
  59
  60                     <entry>
  61                         <methodname>Product_RatingsController::deleteAction()</methodname>
  62                     </entry>
  63                 </row>
  64
  65                 <row>
  66                     <entry><constant>POST</constant></entry>
  67                     <entry><filename>/product/ratings/:id?_method=PUT</filename></entry>
  68                     <entry><methodname>Product_RatingsController::putAction()</methodname></entry>
  69                 </row>
  70
  71                 <row>
  72                     <entry><constant>POST</constant></entry>
  73                     <entry><filename>/product/ratings/:id?_method=DELETE</filename></entry>
  74
  75                     <entry>
  76                         <methodname>Product_RatingsController::deleteAction()</methodname>
  77                     </entry>
  78                 </row>
  79             </tbody>
  80         </tgroup>
  81     </table>
  82
  83     <sect4 id="zend.rest.route_usage">
  84         <title>Zend_Rest_Route Usage</title>
  85
  86         <para>
  87             To enable <classname>Zend_Rest_Route</classname> for an entire
  88             application, construct it with no config params and add it as the
  89             default route on the front controller:
  90         </para>
  91
  92         <programlisting language="php"><![CDATA[
  93 $front     = Zend_Controller_Front::getInstance();
  94 $restRoute = new Zend_Rest_Route($front);
  95 $front->getRouter()->addRoute('default', $restRoute);
  96 ]]></programlisting>
  97
  98         <note>
  99             <para>
 100                 If <classname>Zend_Rest_Route</classname> cannot match a valid
 101                 module, controller, or action, it will return <constant>FALSE</constant> and the
 102                 router will attempt to match using the next route in the router.
 103             </para>
 104         </note>
 105
 106         <para>
 107             To enable <classname>Zend_Rest_Route</classname> for specific modules,
 108             construct it with an array of module names as the 3rd constructor argument:
 109         </para>
 110
 111         <programlisting language="php"><![CDATA[
 112 $front     = Zend_Controller_Front::getInstance();
 113 $restRoute = new Zend_Rest_Route($front, array(), array('product'));
 114 $front->getRouter()->addRoute('rest', $restRoute);
 115 ]]></programlisting>
 116
 117         <para>
 118             To enable <classname>Zend_Rest_Route</classname> for specific
 119             controllers, add an array of controller names as the value of each module array element.
 120         </para>
 121
 122         <programlisting language="php"><![CDATA[
 123 $front     = Zend_Controller_Front::getInstance();
 124 $restRoute = new Zend_Rest_Route($front, array(), array(
 125     'product' => array('ratings')
 126 ));
 127 $front->getRouter()->addRoute('rest', $restRoute);
 128 ]]></programlisting>
 129     </sect4>
 130
 131     <sect4 id="zend.rest.route_config">
 132         <title>Zend_Rest_Route with Zend_Config_Ini</title>
 133
 134         <para>
 135             To use <classname>Zend_Rest_Route</classname> from an <acronym>INI</acronym> config
 136             file, use a route type parameter and set the config options:
 137         </para>
 138
 139         <programlisting language="ini"><![CDATA[
 140 routes.rest.type = Zend_Rest_Route
 141 routes.rest.defaults.controller = object
 142 routes.rest.mod = project,user
 143 ]]></programlisting>
 144
 145         <para>
 146             The 'type' option designates the RESTful routing config type. The 'defaults' option is
 147             used to specify custom default module, controller, and/or actions for the route. All
 148             other options in the config group are treated as RESTful module names, and their values
 149             are RESTful controller names. The example config defines
 150             <classname>Mod_ProjectController</classname> and
 151             <classname>Mod_UserController</classname> as RESTful controllers.
 152         </para>
 153
 154         <para>
 155             Then use the <methodname>addConfig()</methodname> method of the Rewrite router object:
 156         </para>
 157
 158         <programlisting language="php"><![CDATA[
 159 $config = new Zend_Config_Ini('path/to/routes.ini');
 160 $router = new Zend_Controller_Router_Rewrite();
 161 $router->addConfig($config, 'routes');
 162 ]]></programlisting>
 163     </sect4>
 164
 165     <sect4 id="zend.rest.controller">
 166         <title>Zend_Rest_Controller</title>
 167
 168         <para>
 169             To help or guide development of Controllers for use with
 170             <classname>Zend_Rest_Route</classname>, extend your Controllers from
 171             <classname>Zend_Rest_Controller</classname>.
 172             <classname>Zend_Rest_Controller</classname> defines the 5 most-commonly
 173             needed operations for RESTful resources in the form of abstract action
 174             methods.
 175         </para>
 176
 177         <itemizedlist>
 178             <listitem>
 179                 <para>
 180                     <emphasis><methodname>indexAction()</methodname></emphasis> -
 181                     Should retrieve an index of resources and assign it to view.
 182                 </para>
 183             </listitem>
 184
 185             <listitem>
 186                 <para>
 187                     <emphasis><methodname>getAction()</methodname></emphasis> -
 188                     Should retrieve a single resource identified by <acronym>URI</acronym>
 189                     and assign it to view.
 190                 </para>
 191             </listitem>
 192
 193             <listitem>
 194                 <para>
 195                     <emphasis><methodname>postAction()</methodname></emphasis> -
 196                     Should accept a new single resource and persist its state.
 197                 </para>
 198             </listitem>
 199
 200             <listitem>
 201                 <para>
 202                     <emphasis><methodname>putAction()</methodname></emphasis> -
 203                     Should accept a single resource idenitifed by <acronym>URI</acronym>
 204                     and persist its state.
 205                 </para>
 206             </listitem>
 207
 208             <listitem>
 209                 <para>
 210                     <emphasis><methodname>deleteAction()</methodname></emphasis> -
 211                     Should delete a single resource identified by <acronym>URI</acronym>.
 212                 </para>
 213             </listitem>
 214         </itemizedlist>
 215     </sect4>
 216 </sect3>
 217 <!--
 218 vim:se ts=4 sw=4 et:
 219 -->