<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect3 id="zend.controller.router.routes.rest">
    <title>Zend_Rest_Route</title>

    <para>
        Die Komponente <classname>Zend_Rest</classname> enthält eine RESTvolle Route für
        <classname>Zend_Controller_Router_Rewrite</classname>. Diese Route bietet ein
        standardisiertes Routing Schema das Routinganfragen durch Übersetzung der
        <acronym>HTTP</acronym> Methode und der <acronym>URI</acronym> zu einem Modul,
        Controller und einer Action. Die unten stehende Tabelle bietet eine Übersicht darüber
        wie Anfragemethoden und <acronym>URI</acronym>'s geroutet werden.
    </para>

    <table frame="all">
        <title>Verhalten von Zend_Rest_Route</title>

        <tgroup cols='3' align='left' colsep='1' rowsep='1'>
            <colspec colname='method' />
            <colspec colname='URI' />
            <colspec colname='route' />

            <thead>
                <row>
                    <entry>Methode</entry>
                    <entry><acronym>URI</acronym></entry>
                    <entry>Module_Controller::action</entry>
                </row>
            </thead>

            <tbody>
                <row>
                    <entry><constant>GET</constant></entry>
                    <entry><filename>/product/ratings/</filename></entry>
                    <entry><methodname>Product_RatingsController::indexAction()</methodname></entry>
                </row>

                <row>
                    <entry><constant>GET</constant></entry>
                    <entry><filename>/product/ratings/:id</filename></entry>
                    <entry><methodname>Product_RatingsController::getAction()</methodname></entry>
                </row>

                <row>
                    <entry><constant>POST</constant></entry>
                    <entry><filename>/product/ratings</filename></entry>
                    <entry><methodname>Product_RatingsController::postAction()</methodname></entry>
                </row>

                <row>
                    <entry><constant>PUT</constant></entry>
                    <entry><filename>/product/ratings/:id</filename></entry>
                    <entry><methodname>Product_RatingsController::putAction()</methodname></entry>
                </row>

                <row>
                    <entry><constant>DELETE</constant></entry>
                    <entry><filename>/product/ratings/:id</filename></entry>
                    <entry>
                        <methodname>Product_RatingsController::deleteAction()</methodname>
                    </entry>
                </row>

                <row>
                    <entry><constant>POST</constant></entry>
                    <entry><filename>/product/ratings/:id?_method=PUT</filename></entry>
                    <entry><methodname>Product_RatingsController::putAction()</methodname></entry>
                </row>

                <row>
                    <entry><constant>POST</constant></entry>
                    <entry><filename>/product/ratings/:id?_method=DELETE</filename></entry>

                    <entry>
                        <methodname>Product_RatingsController::deleteAction()</methodname>
                    </entry>
                </row>
            </tbody>
        </tgroup>
    </table>

    <sect4 id="zend.rest.route_usage">
        <title>Verwendung von Zend_Rest_Route</title>

        <para>
            Um <classname>Zend_Rest_Route</classname> für eine komplette Anwendung einzuschalten
            muss diese ohne Konfigurationsparameter erstellt und als Standardroute dem
            Frontcontroller hinzugefügt werden:
        </para>

        <programlisting language="php"><![CDATA[
$front     = Zend_Controller_Front::getInstance();
$restRoute = new Zend_Rest_Route($front);
$front->getRouter()->addRoute('default', $restRoute);
]]></programlisting>

        <note>
            <para>
                Wenn <classname>Zend_Rest_Route</classname> keinem gültigen Modul, Controller oder
                keiner Action entspricht gibt diese <constant>FALSE</constant> zurück und der Router
                versucht eine Entsprechung zu finden indem die nächste Route im Router verwendet
                wird.
            </para>
        </note>

        <para>
            Um <classname>Zend_Rest_Route</classname> für spezielle Module einzuschalten muss diese
            mit einem Array von Modulnamen als 3tes Argument des Constructors erstellt werden:
        </para>

        <programlisting language="php"><![CDATA[
$front     = Zend_Controller_Front::getInstance();
$restRoute = new Zend_Rest_Route($front, array(), array('product'));
$front->getRouter()->addRoute('rest', $restRoute);
]]></programlisting>

        <para>
            Um <classname>Zend_Rest_Route</classname> für spezielle Controller einzuschalten muss
            ein Array von Controllernamen als Wert für jedes Modul (Arrayelement) hinzugefügt
            werden.
        </para>

        <programlisting language="php"><![CDATA[
$front     = Zend_Controller_Front::getInstance();
$restRoute = new Zend_Rest_Route($front, array(), array(
    'product' => array('ratings')
));
$front->getRouter()->addRoute('rest', $restRoute);
]]></programlisting>
    </sect4>

    <sect4 id="zend.rest.route_config">
        <title>Zend_Rest_Route mit Zend_Config_Ini</title>

        <para>
            Um <classname>Zend_Rest_Route</classname> von einer <acronym>INI</acronym>
            Konfigurationsdatei aus zu verwenden muss man den "route" Typ Parameter verwenden und
            die Konfigurationsoptionen setzen:
        </para>

        <programlisting language="ini"><![CDATA[routes.rest.type = Zend_Rest_Route
routes.rest.defaults.controller = object
routes.rest.mod = project,user
]]></programlisting>

        <para>
            Die 'type' Option benennt den RESTvollen Routing Konfigurationstyp. Die 'defaults'
            Option wird verwendet um gemeinsame Standardmodule zu spezifizieren, und oder Aktionen
            für die Route. Alle anderen Optionen in der Konfigurationsgruppe werden als RESTvolle
            Modulnamen behandelt, und deren Werte sind RESTvolle Kontrollernamen. Die beispielhafte
            Konfiguration definiert <classname>Mod_ProjectController</classname> und
            <classname>Mod_UserController</classname> als RESTvolle Controller.
        </para>

        <para>
            Dann ist die <methodname>addConfig()</methodname> Methode des Rewrite Router Objekts zu
            verwenden:
        </para>

        <programlisting language="php"><![CDATA[$config = new Zend_Config_Ini('path/to/routes.ini');
$router = new Zend_Controller_Router_Rewrite();
$router->addConfig($config, 'routes');
]]></programlisting>
    </sect4>

    <sect4 id="zend.rest.controller">
        <title>Zend_Rest_Controller</title>

        <para>
            Um bei der Entwicklung von Controllern zu Hilfe zu sein die mit
            <classname>Zend_Rest_Route</classname> verwendet werden, müssen die Controller von
            <classname>Zend_Rest_Controller</classname> erweitert werden.
            <classname>Zend_Rest_Controller</classname> definiert die 5 am meisten benötigten
            Operationen für RESTvolle Ressourcen in der Form von abstrakten Actionmethoden.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis><methodname>indexAction()</methodname></emphasis> -
                    Sollte einen Index von Ressourcen empfangen und diese mit der View
                    verknüpfen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><methodname>getAction()</methodname></emphasis> -
                    Sollte eine einzelne Ressource empfangen die von einer <acronym>URI</acronym>
                    identifiziert wird und diese mit der Vew verknüpfen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><methodname>postAction()</methodname></emphasis> -
                    Sollte eine einzelne neue Ressource akzeptieren und dessen Status persistent
                    machen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><methodname>putAction()</methodname></emphasis> -
                    Sollte eine einzelne Ressource akzeptieren die von einer <acronym>URI</acronym>
                    identifiziert wird und dessen Status persistent machen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><methodname>deleteAction()</methodname></emphasis> -
                    Sollte eine einzelne Ressource löschen die von einer <acronym>URI</acronym>
                    identifiziert wird.
                </para>
            </listitem>
        </itemizedlist>
    </sect4>
</sect3>
