repo_zf1/documentation/manual/fr/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>Introduction</title>

        <para>
            Utiliser le <classname>Zend_Rest_Client</classname> est très semblable à
            l'utilisation des objets de <code>SoapClient</code> (<ulink
            url="http://www.php.net/soap">SOAP web service extension</ulink>). Vous pouvez
            simplement appeler les procédures de service de REST comme méthodes de
            <classname>Zend_Rest_Client</classname>. Vous devez indiquer l'adresse complète du
            service dans le constructeur de <classname>Zend_Rest_Client</classname>.
        </para>

        <example id="zend.rest.client.introduction.example-1">
            <title>Une requête REST basique</title>

            <programlisting language="php"><![CDATA[
/**
 * Connexion au serveur framework.zend.com server
 */
require_once 'Zend/Rest/Client.php';

$client = new Zend_Rest_Client('http://framework.zend.com/rest');

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

        <note>
            <title>Différences dans les appels</title>

            <para>
                <classname>Zend_Rest_Client</classname> tente de rendre les méthodes distantes
                de la même manière que ses propres méthodes, la seule différence étant que vous
                devez suivre l'appel de méthode <methodname>get()</methodname>, <methodname>post()</methodname>,
                <methodname>put()</methodname> ou <methodname>delete()</methodname>. Cet appel peut être fait par
                l'intermédiaire de méthodes enchaînées ou dans des appels séparés de méthode
                :
            </para>

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

    <sect2 id="zend.rest.client.return">
        <title>Réponses</title>

        <para>
            Toutes les demandes faites en utilisant <classname>Zend_Rest_Client</classname>
            retourne un objet <classname>Zend_Rest_Client_Response</classname>. Cet objet a beaucoup
            de propriétés qui facilitent l'accès aux résultats.
        </para>

        <para>
            Quand le service est basé sur <classname>Zend_Rest_Server</classname>,
            Zend_Rest_Client peut faire plusieurs suppositions au sujet de la réponse, y compris le
            statut de réponse (succès ou échec) et le type de retour.
        </para>

        <example id="zend.rest.client.return.example-1">
            <title>État de la réponse</title>

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

if ($result->isSuccess()) {
    echo $result; // "Hello Davey, Good Day"
}
]]></programlisting>
        </example>

        <para>
            Dans l'exemple ci-dessus, vous pouvez voir que nous utilisons le résultat de la
            demande comme un objet, pour appeler <methodname>isSuccess()</methodname>, et puis grâce à
            <methodname>__toString()</methodname>, nous pouvons simplement faire <code>echo</code> sur l'objet
            pour récupérer le résultat. <classname>Zend_Rest_Client_Response</classname> vous
            permettra de afficher n'importe quelle valeur scalaire. Pour les types complexes, vous
            pouvez employer la notation type objet ou type tableau.
        </para>

        <para>
            Si cependant, vous souhaitez questionner un service n'employant pas
            <classname>Zend_Rest_Server</classname> l'objet de
            <classname>Zend_Rest_Client_Response</classname> se comportera comme un
            <code>SimpleXMLElement</code>. Cependant, pour faciliter les choses, il questionnera
            automatiquement le <acronym>XML</acronym> en utilisant XPath si la propriété n'est pas un descendant direct
            de l'élément racine du document. En plus, si vous accédez à une propriété comme à une
            méthode, vous recevrez la valeur de <acronym>PHP</acronym> pour l'objet, ou un tableau de résultats.
        </para>

        <example id="zend.rest.client.return.example-2">
            <title>Utiliser le service REST Technorati</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>Exemple de réponse Technorati</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>
            Ici nous accédons aux propriétés <code>firstname</code> et
            <code>lastname</code>.Bien que ce ne soient pas les éléments supérieurs, elles sont
            automatiquement retournées quand on accède par le nom.
        </para>

        <note>
            <title>Éléments multiples</title>

            <para>
                Si des éléments multiples sont trouvés en accédant à une valeur de nom, un
                tableau d'élément SimpleXMLElement sera retourné ; l'accès par l'intermédiaire de la
                notation de méthode retournera un tableau de valeurs.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.rest.client.args">
        <title>Arguments de requêtes</title>

        <para>
            A moins que vous ne fassiez une demande à un service basé sur
            <classname>Zend_Rest_Server</classname>, il y a des chances que vous devez envoyer des
            arguments multiples avec votre requête. Ceci est fait en appelant une méthode avec le
            nom de l'argument, en passant la valeur comme premier (et seul) argument. Chacun de ces
            appels de méthode renvoie l'objet lui-même, tenant compte de l'enchaînement, ou de
            l'utilisation habituelle. Le premier appel, ou le premier argument si vous passez plus
            d'un argument, est toujours considéré comme la méthode en appelant un service
            <classname>Zend_Rest_Server</classname>.
        </para>

        <example id="zend.rest.client.args.example-1">
            <title>Affecter des arguments de requêtes</title>

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

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

// or

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

        <para>
            Les deux méthodes dans l'exemple ci-dessus, auront comme conséquence l'obtention
            des arguments suivants :
            <code>?method=arg&amp;arg1=value1&amp;arg=value1&amp;arg2=value2</code>
        </para>

        <para>
            Vous noterez que le premier appel de <code>$client-&gt;arg('value1');</code> a eu
            comme conséquence <code>method=arg&amp;arg1=value1</code> et <code>arg=value1</code> ;
            ceci afin que <classname>Zend_Rest_Server</classname> puisse comprendre la demande
            correctement, plutôt que d'exiger la connaissance préalable du service.
        </para>

        <warning>
            <title>Sévérité de Zend_Rest_Client</title>

            <para>
                Tout service REST qui est strict au sujet des arguments qu'il reçoit échouera
                probablement en utilisant <classname>Zend_Rest_Client</classname>, en raison du
                comportement décrit ci-dessus. Ce n'est pas une pratique courante et ne devrait pas
                poser des problèmes.
            </para>
        </warning>
    </sect2>
</sect1>