repo_zf1/documentation/manual/de/module_specs/Zend_Rest_Client.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.rest.client">
    <title>Zend_Rest_Client</title>

    <sect2 id="zend.rest.client.introduction">
        <title>Einführung</title>

        <para>
            Die Verwendung von <classname>Zend_Rest_Client</classname> ist sehr ähnlich der
            Verwendung von <code>SoapClient</code> Objekten (<ulink
                url="http://www.php.net/soap">SOAP Web Service Erweiterung</ulink>). Man kann
            einfach die REST Service Prozeduren als <classname>Zend_Rest_Client</classname> Methoden
            aufrufen. Spezifiziere die komplette Adresse des Services im Constructor von
            <classname>Zend_Rest_Client</classname>.
        </para>

        <example id="zend.rest.client.introduction.example-1">
            <title>Eine Basis REST Anfrage</title>

            <programlisting language="php"><![CDATA[
/**
 * Verbinden zum framework.zend.com Server und eine Begrüßung empfangen
 */
$client = new Zend_Rest_Client('http://framework.zend.com/rest');

echo $client->sayHello('Davey', 'Day')->get(); // "Servus Davey, guten Tag"
]]></programlisting>
        </example>

        <note>
            <title>Unterschiede im Aufruf</title>

            <para>
                <classname>Zend_Rest_Client</classname> versucht, dass die entfernten Methoden, so
                weit wie möglich, wie die nativen Methoden aussehen, wobei der einzige Unterschied
                darin besteht, dass der Methodenaufruf mit <methodname>get()</methodname>,
                <methodname>post()</methodname>, <methodname>put()</methodname> oder
                <methodname>delete()</methodname> erfolgen muß. Dieser Aufruf kann entweder über
                Methoden Verkettung oder in eigenen Methodenaufrufen erfolgen:
            </para>

            <programlisting language="php"><![CDATA[
$client->sayHello('Davey', 'Tag');
echo $client->get();
]]></programlisting>
        </note>
    </sect2>

    <sect2 id="zend.rest.client.return">
        <title>Antworten</title>

        <para>
            Alle Anfragen die über <classname>Zend_Rest_Client</classname> gemacht wurden,
            liefern ein <classname>Zend_Rest_Client_Response</classname> Objekt zurück. Dieses
            Objekt hat viele Eigenschaften, was es einfacher macht, auf die Ergebnisse zuzugreifen.
        </para>

        <para>
            Wenn ein Service auf <classname>Zend_Rest_Server</classname> basiert, kann
            <classname>Zend_Rest_Client</classname> einige Annahmen über die Antwort treffen,
            inklusive dem Antwort Status (erfolgreich oder fehlerhaft) und den Rückgabetyp.
        </para>

        <example id="zend.rest.client.return.example-1">
            <title>Antwort Status</title>

            <programlisting language="php"><![CDATA[
$result = $client->sayHello('Davey', 'Tag')->get();

if ($result->isSuccess()) {
    echo $result; // "Hallo Davey, guten Tag"
}
]]></programlisting>
        </example>

        <para>
            Im obigen Beispiel kann man sehen, dass das Ergebnis der Anfrage als Objekt verwendet
            wird, um <methodname>isSuccess()</methodname> aufzurufen. Mithilfe der magischen
            <methodname>__toString()</methodname>-Methode kann man das Objekt bzw. das Ergebnis
            ausgeben (<code>echo</code>). <classname>Zend_Rest_Client_Response</classname> erlaubt
            die Ausgabe jedes skalaren Wertes. Für komplexe Typen, kann entweder die Array- oder die
            Objektschreibweise verwendet werden.
        </para>

        <para>
            Wenn trotzdem ein Service abgefragt wird, der nicht
            <classname>Zend_Rest_Server</classname> verwendet, wird sich das
            <classname>Zend_Rest_Client_Response</classname> Objekt mehr wie ein
            <code>SimpleXMLElement</code> verhalten. Um die Dinge trotzdem einfacher zu gestalten,
            wird das <acronym>XML</acronym> automatisch abgefragt, indem XPath verwendet wird, wenn
            die Eigenschaft nicht von direkter Abstammung des Dokument Root-Elements ist.
            Zusätzlich, wenn auf eine Eigenschaft als Methode zugegriffen wird, empfängt man den
            <acronym>PHP</acronym> Wert für das Objekt, oder ein Array mit den
            <acronym>PHP</acronym> Wert Ergebnissen.
        </para>

        <example id="zend.rest.client.return.example-2">
            <title>Technorati's REST Service verwenden</title>

            <programlisting language="php"><![CDATA[
$technorati = new Zend_Rest_Client('http://api.technorati.com/bloginfo');
$technorati->key($key);
$technorati->url('http://pixelated-dreams.com');
$result = $technorati->get();
echo $result->firstname() .' '. $result->lastname();
]]></programlisting>
        </example>

        <example id="zend.rest.client.return.example-3">
            <title>Beispiel Technorati Antwort</title>

            <programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="utf-8"?>
<!-- generator="Technorati API version 1.0 /bloginfo" -->
<!DOCTYPE tapi PUBLIC "-//Technorati, Inc.//DTD TAPI 0.02//EN"
                      "http://api.technorati.com/dtd/tapi-002.xml">
<tapi version="1.0">
    <document>
        <result>
            <url>http://pixelated-dreams.com</url>
            <weblog>
                <name>Pixelated Dreams</name>
                <url>http://pixelated-dreams.com</url>
                <author>
                    <username>DShafik</username>
                    <firstname>Davey</firstname>
                    <lastname>Shafik</lastname>
                </author>
                <rssurl>
                    http://pixelated-dreams.com/feeds/index.rss2
                </rssurl>
                <atomurl>
                    http://pixelated-dreams.com/feeds/atom.xml
                </atomurl>
                <inboundblogs>44</inboundblogs>
                <inboundlinks>218</inboundlinks>
                <lastupdate>2006-04-26 04:36:36 GMT</lastupdate>
                <rank>60635</rank>
            </weblog>
            <inboundblogs>44</inboundblogs>
            <inboundlinks>218</inboundlinks>
        </result>
    </document>
</tapi>
]]></programlisting>
        </example>

        <para>
            Hier greifen wir auf die <code>firstname</code> und <code>lastname</code> Eigenschaften
            zu. Selbst wenn diese keine Top-Level Elemente sind, werden Sie automatisch
            zurückgegeben, wenn auf sie durch ihren Namen zugegriffen wird.
        </para>

        <note>
            <title>Mehrere Elemente</title>

            <para>
                Wenn beim Zugriff, über einen Namen, mehrere Elemente mit demselben Namen gefunden
                werden, wird ein Array von SimpleXML-Elementen zurückgegeben. Beim Zugriff über die
                Methodenschreibweise wird ein Array von <acronym>PHP</acronym> Werten zurückgegeben.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.rest.client.args">
        <title>Anfrage Argumente</title>

        <para>
            Wenn man eine Anfrage an einen Server sendet, welcher nicht auf
            <classname>Zend_Rest_Server</classname> basiert, sind die Chancen groß, dass man mehrere
            Argumente mit der Anfrage senden muß. Das wird durchgeführt, indem man eine Methode mit
            dem Namen des Arguments aufruft und den Wert, als das erste (und einzige) Argument
            übergibt. Jeder dieser Methodenaufrufe, gibt das Objekt selbst zurück, was Verkettung
            oder "flüssige" Verwendung erlaubt. Der erste Aufruf, oder das erste Argument, das
            übergeben wird, wenn man mehr als ein Argument übergeben will, wird immer als die
            Methode angenommen wenn ein <classname>Zend_Rest_Server</classname> Service aufgerufen
            wird.
        </para>

        <example id="zend.rest.client.args.example-1">
            <title>Anfrage Argumente setzen</title>

            <programlisting language="php"><![CDATA[
$client = new Zend_Rest_Client('http://example.org/rest');

$client->arg('value1');
$client->arg2('value2');
$client->get();

// oder

$client->arg('value1')->arg2('value2')->get();
]]></programlisting>
        </example>

        <para>
            Beide Varianten im obigen Beispiel, ergeben die folgenden get-Argumente:
            <code>?method=arg&amp;arg1=value1&amp;arg=value1&amp;arg2=value2</code>
        </para>

        <para>
            Es gilt zu bemerken, dass der erste Aufruf von <code>$client->arg('value1');</code> in
            beidem resultiert: <code>method=arg&amp;arg1=value1</code> und <code>arg=value1</code>.
            Es ist so, dass <classname>Zend_Rest_Server</classname> die Anfrage korrekt versteht,
            ohne dass vordefiniertes Wissen über das Service benötigt wird.
        </para>

        <warning>
            <title>Striktheit von Zend_Rest_Client</title>

            <para>
                Jeder REST Service der strikt in seinen Argumenten ist, die er empfängt, wird wegen
                dem oben beschriebenen Verhalten bei der Verwendung von
                <classname>Zend_Rest_Client</classname> fehlschlagen. Das ist keine gewöhnliche
                Praxis und sollte keine Probleme verursachen.
            </para>
        </warning>
    </sect2>
</sect1>